feat: Add tags to a taxonomy

package.json

@@ -66,6 +66,7 @@
     "@openedx/paragon": "^23.5.0",
     "@redux-devtools/extension": "^3.3.0",
     "@reduxjs/toolkit": "2.11.2",
+    "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-query": "5.90.21",
     "@tinymce/tinymce-react": "^6.0.0",
     "classnames": "2.5.1",

src/taxonomy/data/api.ts

@@ -57,9 +57,16 @@ export const apiUrls = {
    * @param pageIndex Zero-indexed page number
    * @param pageSize How many tags per page to load
    */
-  tagList: (taxonomyId: number, pageIndex: number, pageSize: number) => makeUrl(`${taxonomyId}/tags/`, {
-    page: (pageIndex + 1), page_size: pageSize,
-  }),
+  tagList: (taxonomyId: number, pageIndex: number | null, pageSize: number | null, fullDepthThreshold?: number) => {
+    if (pageIndex === null) {
+      return makeUrl(`${taxonomyId}/tags/`, { full_depth_threshold: fullDepthThreshold || 0 });
+    }
+    return makeUrl(`${taxonomyId}/tags/`, {
+      page: (pageIndex ?? 0) + 1,
+      page_size: pageSize ?? 10,
+      full_depth_threshold: fullDepthThreshold || 0,
+    });
+  },
   /**
    * Get _all_ tags below a given parent tag. This may be replaced with something more scalable in the future.
    */
@@ -74,6 +81,7 @@ export const apiUrls = {
   tagsImport: (taxonomyId) => makeUrl(`${taxonomyId}/tags/import/`),
   /** URL to plan (preview what would happen) a taxonomy import */
   tagsPlanImport: (taxonomyId: number) => makeUrl(`${taxonomyId}/tags/import/plan/`),
+  createTag: (taxonomyId: number) => makeUrl(`${taxonomyId}/tags/`),
 } satisfies Record<string, (...args: any[]) => string>;
 
 /**

src/taxonomy/data/apiHooks.test.jsx

@@ -11,6 +11,7 @@ import MockAdapter from 'axios-mock-adapter';
 import { apiUrls } from './api';
 
 import {
+  useCreateTag,
   useImportPlan,
   useImportTags,
   useImportNewTaxonomy,
@@ -105,4 +106,12 @@ describe('import taxonomy api calls', () => {
     expect(result.current.error).toEqual(Error('test error'));
     expect(axiosMock.history.put[0].url).toEqual(apiUrls.tagsPlanImport(1));
   });
+
+  it('should surface duplicate tag error returned as an array', async () => {
+    const duplicateError = "Tag with value 'ab' already exists for taxonomy.";
+    axiosMock.onPost(apiUrls.createTag(1)).reply(400, [duplicateError]);
+    const { result } = renderHook(() => useCreateTag(1), { wrapper });
+
+    await expect(result.current.mutateAsync({ value: 'ab' })).rejects.toEqual(Error(duplicateError));
+  });
 });

src/taxonomy/data/apiHooks.ts

@@ -16,6 +16,7 @@ import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
 import { apiUrls, ALL_TAXONOMIES } from './api';
 import * as api from './api';
 import type { QueryOptions, TagListData } from './types';
+import { EXPECTED_MAX_TAXONOMY_ITEMS } from './constants';
 
 // Query key patterns. Allows an easy way to clear all data related to a given taxonomy.
 // https://github.com/openedx/frontend-app-admin-portal/blob/2ba315d/docs/decisions/0006-tanstack-react-query.rst
@@ -65,6 +66,37 @@ export const taxonomyQueryKeys = {
   importPlan: (taxonomyId: number, fileId: string) => [...taxonomyQueryKeys.all, 'importPlan', taxonomyId, fileId],
 } satisfies Record<string, (string | number)[] | ((...args: any[]) => (string | number)[])>;
 
+const getApiErrorMessage = (err: unknown): string => {
+  const error = err as { message?: string; response?: { data?: unknown } };
+  const responseData = error?.response?.data;
+
+  if (Array.isArray(responseData)) {
+    const firstMessage = responseData.find((item): item is string => typeof item === 'string' && item.trim().length > 0);
+    if (firstMessage) {
+      return firstMessage;
+    }
+  }
+
+  if (typeof responseData === 'string' && responseData.trim().length > 0) {
+    return responseData;
+  }
+
+  if (responseData && typeof responseData === 'object') {
+    const objectData = responseData as { error?: string; detail?: string; message?: string };
+    if (typeof objectData.error === 'string' && objectData.error.trim().length > 0) {
+      return objectData.error;
+    }
+    if (typeof objectData.detail === 'string' && objectData.detail.trim().length > 0) {
+      return objectData.detail;
+    }
+    if (typeof objectData.message === 'string' && objectData.message.trim().length > 0) {
+      return objectData.message;
+    }
+  }
+
+  return error?.message || 'Unexpected error';
+};
+
 /**
  * Builds the query to get the taxonomy list
  * @param {string} [org] Filter the list to only show taxonomies assigned to this org
@@ -139,7 +171,7 @@ export const useImportTags = () => {
         const { data } = await getAuthenticatedHttpClient().put(apiUrls.tagsImport(taxonomyId), formData);
         return camelCaseObject(data);
       } catch (err) {
-        throw new Error((err as any).response?.data?.error || (err as any).message);
+        throw new Error(getApiErrorMessage(err));
       }
     },
     onSuccess: (data) => {
@@ -170,7 +202,7 @@ export const useImportPlan = (taxonomyId: number, file: File | null) => useQuery
       const { data } = await getAuthenticatedHttpClient().put(apiUrls.tagsPlanImport(taxonomyId), formData);
       return data.plan as string;
     } catch (err) {
-      throw new Error((err as any).response?.data?.error || (err as any).message);
+      throw new Error(getApiErrorMessage(err));
     }
   },
   retry: false, // If there's an error, it's probably a real problem with the file. Don't try again several times!
@@ -180,13 +212,17 @@ export const useImportPlan = (taxonomyId: number, file: File | null) => useQuery
  * Use the list of tags in a taxonomy.
  */
 export const useTagListData = (taxonomyId: number, options: QueryOptions) => {
-  const { pageIndex, pageSize } = options;
+  const { pageIndex, pageSize, enabled = true } = options; // eslint-disable-line
   return useQuery({
-    queryKey: taxonomyQueryKeys.taxonomyTagListPage(taxonomyId, pageIndex, pageSize),
+    // queryKey: taxonomyQueryKeys.taxonomyTagListPage(taxonomyId, pageIndex, pageSize),
+    queryKey: taxonomyQueryKeys.taxonomyTagList(taxonomyId), // For now, ignore pagination in the query key.
     queryFn: async () => {
-      const { data } = await getAuthenticatedHttpClient().get(apiUrls.tagList(taxonomyId, pageIndex, pageSize));
+      const { data } = await getAuthenticatedHttpClient().get(
+        apiUrls.tagList(taxonomyId, null, null, EXPECTED_MAX_TAXONOMY_ITEMS),
+      );
       return camelCaseObject(data) as TagListData;
     },
+    enabled,
   });
 };
 
@@ -202,3 +238,27 @@ export const useSubTags = (taxonomyId: number, parentTagValue: string) => useQue
     return camelCaseObject(response.data) as TagListData;
   },
 });
+
+export const useCreateTag = (taxonomyId: number) => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ value, parentTagValue }: { value: string, parentTagValue?: string }) => {
+      try {
+        await getAuthenticatedHttpClient().post(
+          apiUrls.createTag(taxonomyId),
+          { tag: value, parent_tag_value: parentTagValue },
+        );
+      } catch (err) {
+        throw new Error(getApiErrorMessage(err));
+      }
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: taxonomyQueryKeys.taxonomyTagList(taxonomyId),
+      });
+      // In the metadata, 'tagsCount' (and possibly other fields) will have changed:
+      queryClient.invalidateQueries({ queryKey: taxonomyQueryKeys.taxonomyMetadata(taxonomyId) });
+    },
+  });
+};

src/taxonomy/data/constants.ts

@@ -0,0 +1,8 @@
+/**
+ * The maximum number of taxonomy items expected.
+ * This is used to set `full_depth_threshold` for the tag list API endpoint,
+ * which determines when to include the `full_depth` field in the response.
+ * Right now we expect to load all tags for a taxonomy in one request,
+ * and we just set this number really high to avoid any edge cases.
+ */
+export const EXPECTED_MAX_TAXONOMY_ITEMS = 10000;

src/taxonomy/data/types.ts

@@ -32,6 +32,7 @@ export interface TaxonomyListData {
 export interface QueryOptions {
   pageIndex: number;
   pageSize: number;
+  enabled?: boolean;
 }
 
 export interface TagData {

src/taxonomy/tag-list/OptionalExpandLink.test.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import { IntlProvider } from '@edx/frontend-platform/i18n';
+import { fireEvent, render, screen } from '@testing-library/react';
+
+import OptionalExpandLink from './OptionalExpandLink';
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <IntlProvider locale="en" messages={{}}>{children}</IntlProvider>
+);
+
+const createMockRow = ({
+  canExpand = true,
+  isExpanded = false,
+  toggleHandler = jest.fn(),
+} = {}) => ({
+  getCanExpand: () => canExpand,
+  getIsExpanded: () => isExpanded,
+  getToggleExpandedHandler: () => toggleHandler,
+}) as any;
+
+describe('OptionalExpandLink', () => {
+  it('hides expand button when row cannot expand', () => {
+    render(<OptionalExpandLink row={createMockRow({ canExpand: false })} />, { wrapper });
+    const button = screen.getByRole('button', { hidden: true });
+
+    expect(button).toBeDisabled();
+    expect(button).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('renders show subtags control and toggles for collapsed row', () => {
+    const toggleHandler = jest.fn();
+    const row = createMockRow({ canExpand: true, isExpanded: false, toggleHandler });
+
+    render(<OptionalExpandLink row={row} />, { wrapper });
+    const button = screen.getByRole('button', { name: 'Show Subtags' });
+
+    expect(button).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.click(button);
+    expect(toggleHandler).toHaveBeenCalled();
+  });
+
+  it('renders hide subtags control for expanded row', () => {
+    const row = createMockRow({ canExpand: true, isExpanded: true });
+
+    render(<OptionalExpandLink row={row} />, { wrapper });
+    const button = screen.getByRole('button', { name: 'Hide Subtags' });
+
+    expect(button).toHaveAttribute('aria-expanded', 'true');
+  });
+});

src/taxonomy/tag-list/OptionalExpandLink.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { IconButton } from '@openedx/paragon';
+import { ExpandLess, ExpandMore } from '@openedx/paragon/icons';
+import { Row } from '@tanstack/react-table';
+import { useIntl } from '@edx/frontend-platform/i18n';
+
+import type { TreeRowData } from '../tree-table/types';
+import messages from './messages';
+
+interface OptionalExpandLinkProps {
+  row?: Row<TreeRowData>;
+  forceHide?: boolean;
+}
+
+/** OptionalExpandLink
+ * Renders an optional expand/collapse button for a tanstack/react-table row.
+ *
+ * For simplicity, this just hides the button if the row can't be expanded,
+ * in order to maintain a correctly-sized placeholder.
+ */
+const OptionalExpandLink = ({ row, forceHide = false }: OptionalExpandLinkProps) => {
+  const intl = useIntl();
+  const canExpand = !!row?.getCanExpand() && !forceHide;
+
+  if (!canExpand) {
+    return (
+      <IconButton
+        src={ExpandMore}
+        alt=""
+        size="sm"
+        className="mr-1 invisible"
+        disabled
+        tabIndex={-1}
+        aria-hidden
+      />
+    );
+  }
+
+  const isExpanded = !!row?.getIsExpanded();
+  const buttonLabel = isExpanded
+    ? intl.formatMessage(messages.hideSubtagsButtonLabel)
+    : intl.formatMessage(messages.showSubtagsButtonLabel);
+
+  return (
+    <IconButton
+      src={isExpanded ? ExpandLess : ExpandMore}
+      onClick={row?.getToggleExpandedHandler()}
+      alt={buttonLabel}
+      aria-label={buttonLabel}
+      aria-expanded={isExpanded}
+      size="sm"
+      className="mr-1"
+    />
+  );
+};
+
+export default OptionalExpandLink;