Merge pull request #879 from IABTechLab/ibg-CORPWEB-3558-update-custom-tags

ibg-CORPWEB-3558-update-custom-tags

Author: ibgrav

.gitignore

@@ -18,3 +18,4 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.aider*

README.md

@@ -1,10 +1,39 @@
 # UID2 Documentation
 
->Note: The new location for viewing UID2 documentation content is on the Unified ID website: [Unified ID 2.0 Overview](https://unifiedid.com/docs/intro).
+> Note: The new location for viewing UID2 documentation content is on the Unified ID website: [Unified ID 2.0 Overview](https://unifiedid.com/docs/intro).
 
 This repository contains all the content files and supporting site infrastructure for the [Unified ID 2.0 website](https://unifiedid.com). Site content is available in the following languages:
 
 - English (US)
 - Japanese
 
 For information about build tools and about contributing to this repository, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Adding custom tags
+
+1. Add imports to top of markdown file body
+
+```ts
+import CustomTagsFilters from "@site/src/components/CustomTags/CustomTagsFilters";
+import CustomTagsContainer from "@site/src/components/CustomTags/CustomTagsContainer";
+```
+
+2. Render `CustomTagsFilters` in desired location - probably at top of page below heading.
+
+```tsx
+<CustomTagsFilters />
+```
+
+3. Wrap tagged section with CustomTagsContainer and add desired tags, comma-separated
+
+```mdx
+<CustomTagsContainer tags="tag one, tag two">
+
+### My Tagged Section
+
+The body of my tagged section. <a href="">An example link.</a>
+
+</CustomTagsContainer>
+```
+
+4. All added tags should now appear as clickable tag buttons at the top of the page. Clicking a tag will filter only results that match that tag. Clicking the tag again should toggle all content to be visible.

src/components/CustomTags/CustomTagsContainer.tsx

@@ -0,0 +1,36 @@
+import styles from "./styles.module.scss";
+import { ReactNode, useContext, useEffect } from "react";
+import { CustomTagsContext } from "./CustomTagsContext";
+
+export interface CustomTagsContainerProps {
+  tags: string; // comma-separated values
+  title: string;
+  children: ReactNode;
+}
+
+export default function CustomTagsContainer({
+  tags = "",
+  children,
+}: CustomTagsContainerProps) {
+  const [{ filter }, setState] = useContext(CustomTagsContext);
+
+  const tagList = tags.split(",").map((tag) => tag.trim());
+
+  useEffect(() => {
+    setState((state) => ({
+      ...state,
+      // create unique array of all tags
+      tags: Array.from(new Set([...state.tags, ...tagList])),
+    }));
+  }, [tags]);
+
+  return (
+    <div
+      className={
+        tagList.includes(filter) ? styles["custom-tags-container-visible"] : ""
+      }
+    >
+      {children}
+    </div>
+  );
+}

src/components/CustomTags/CustomTagsContext.tsx

@@ -0,0 +1,29 @@
+import {
+  createContext,
+  Dispatch,
+  PropsWithChildren,
+  SetStateAction,
+  useState,
+} from "react";
+
+type TagState = {
+  tags: string[];
+  filter: string | undefined;
+};
+
+type TagContext = [TagState, Dispatch<SetStateAction<TagState>>];
+
+export const CustomTagsContext = createContext<TagContext>(undefined);
+
+export function CustomTagsContextProvider({ children }: PropsWithChildren) {
+  const [state, setState] = useState<TagState>({
+    tags: [],
+    filter: undefined,
+  });
+
+  return (
+    <CustomTagsContext.Provider value={[state, setState]}>
+      {children}
+    </CustomTagsContext.Provider>
+  );
+}

src/components/CustomTags/CustomTagsFilterList.tsx

@@ -0,0 +1,50 @@
+import { CSSProperties, useContext } from "react";
+import styles from "./styles.module.scss";
+import { CustomTagsContext } from "./CustomTagsContext";
+
+interface CustomTagsFilterListProps {
+  tags: string[];
+  style?: CSSProperties;
+  subtitle?: string;
+}
+
+export function CustomTagsFilterList({
+  tags,
+  style,
+  subtitle,
+}: CustomTagsFilterListProps) {
+  const [{ filter }, setState] = useContext(CustomTagsContext);
+
+  if (tags.length < 1) return null;
+
+  const onClickFilter = (update: string) => {
+    if (filter === update) update = undefined; // toggle off
+
+    setState((state) => ({ ...state, filter: update }));
+
+    const article = document.querySelector("article");
+
+    if (article) {
+      article.classList[update ? "add" : "remove"](
+        styles["custom-tag-toggled"],
+      );
+    }
+  };
+
+  return (
+    <div className={styles["custom-tags-filters"]} style={style}>
+      {subtitle && <b>{subtitle}</b>}
+
+      <ul>
+        {tags.map((tag) => (
+          <li
+            key={tag}
+            className={filter === tag ? styles["custom-tags-active"] : ""}
+          >
+            <button onClick={() => onClickFilter(tag)}>{tag}</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}

src/components/CustomTags/CustomTagsFilters.tsx

@@ -0,0 +1,9 @@
+import { useContext } from "react";
+import { CustomTagsContext } from "./CustomTagsContext";
+import { CustomTagsFilterList } from "./CustomTagsFilterList";
+
+export default function CustomTagsFilters() {
+  const [{ tags }] = useContext(CustomTagsContext);
+
+  return <CustomTagsFilterList tags={tags} subtitle="Tags: " />;
+}

src/components/CustomTags/styles.module.scss

@@ -0,0 +1,57 @@
+.custom-tags-filters {
+  display: flex;
+  flex-flow: row;
+  gap: 0.5em;
+  margin: 0 0 1.5em 0;
+  padding: 0;
+
+  ul {
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-flow: row;
+    gap: 0.5em;
+  }
+
+  li {
+    margin: 0 !important;
+    list-style-type: none;
+
+    button {
+      cursor: pointer;
+      background-color: inherit;
+
+      // styles coppied from /blog theme tag
+      border-radius: var(--ifm-global-radius);
+      padding: 0.2rem 0.5rem 0.3rem;
+      font-size: 90%;
+      border: 1px solid var(--docusaurus-tag-list-border);
+      transition: border var(--ifm-transition-fast);
+      color: var(--ifm-link-color);
+
+      &:hover {
+        --docusaurus-tag-list-border: var(--ifm-link-color);
+      }
+    }
+  }
+}
+
+.custom-tags-active {
+  button {
+    --docusaurus-tag-list-border: var(--ifm-link-color);
+  }
+}
+
+.custom-tags-container-visible {
+  display: block;
+}
+
+.custom-tag-toggled {
+  // all siblings after first paragraph, except for tags and filtered container
+  p:first-of-type
+    ~ *:not(.custom-tags-filters):not(.custom-tags-container-visible):not(
+      .custom-tags-container-visible *
+    ) {
+    display: none;
+  }
+}

src/theme/Layout/Provider/index.tsx

@@ -13,6 +13,7 @@ import {
   PluginHtmlClassNameProvider,
 } from "@docusaurus/theme-common/internal";
 import { DocsPreferredVersionContextProvider } from "@docusaurus/plugin-content-docs/client";
+import { CustomTagsContextProvider } from "@site/src/components/CustomTags/CustomTagsContext";
 
 const Provider = composeProviders([
   ColorModeProvider,
@@ -38,8 +39,10 @@ export default function LayoutProvider({ children }) {
 
   return (
     <Provider>
-      {isDocsPage ? <RestoreTheme></RestoreTheme> : null}
-      {children}
+      <CustomTagsContextProvider>
+        {isDocsPage ? <RestoreTheme></RestoreTheme> : null}
+        {children}
+      </CustomTagsContextProvider>
     </Provider>
   );
 }

tsconfig.json

@@ -4,6 +4,7 @@
   "compilerOptions": {
     "baseUrl": ".",
     "resolveJsonModule": true,
+    "jsx": "react-jsx",
     "paths": {
       "@site/*": ["./*"]
     }