@widlarzgroup/docusaurus-ui 0.0.1

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -0,0 +1,403 @@
+import React, {
+  type ComponentProps,
+  type ReactNode,
+  useEffect,
+  useMemo,
+} from 'react';
+import clsx from 'clsx';
+import {
+  ThemeClassNames,
+  useThemeConfig,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+} from '@docusaurus/theme-common';
+import { isSamePath } from '@docusaurus/theme-common/internal';
+import {
+  isActiveSidebarItem,
+  findFirstSidebarItemLink,
+  useDocSidebarItemsExpandedState,
+  useVisibleSidebarItems,
+} from '@docusaurus/plugin-content-docs/client';
+import Link from '@docusaurus/Link';
+import { translate } from '@docusaurus/Translate';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import DocSidebarItems from '@theme-original/DocSidebarItems';
+import DocSidebarItemLink from '@theme-original/DocSidebarItem/Link';
+import type { Props } from '@theme/DocSidebarItem/Category';
+import ProBadge from '@/components/ProBadge/ProBadge';
+import StatusBadge from '@/components/StatusBadge/StatusBadge';
+import type {
+  WithCustomProps,
+  CustomSidebarProps,
+} from '@/types/sidebar';
+
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+import styles from './styles.module.css';
+
+// If we navigate to a category and it becomes active, it should automatically
+// expand itself
+function useAutoExpandActiveCategory({
+  isActive,
+  collapsed,
+  updateCollapsed,
+  activePath,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  updateCollapsed: (b: boolean) => void;
+  activePath: string;
+}) {
+  const wasActive = usePrevious(isActive);
+  const previousActivePath = usePrevious(activePath);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    const stillActiveButPathChanged =
+      isActive && wasActive && activePath !== previousActivePath;
+    if ((justBecameActive || stillActiveButPathChanged) && collapsed) {
+      updateCollapsed(false);
+    }
+  }, [
+    isActive,
+    wasActive,
+    collapsed,
+    updateCollapsed,
+    activePath,
+    previousActivePath,
+  ]);
+}
+
+/**
+ * When a collapsible category has no link, we still link it to its first child
+ * during SSR as a temporary fallback. This allows to be able to navigate inside
+ * the category even when JS fails to load, is delayed or simply disabled
+ * React hydration becomes an optional progressive enhancement
+ * see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
+ * see https://github.com/facebook/docusaurus/issues/3030
+ */
+function useCategoryHrefWithSSRFallback(
+  item: Props['item']
+): string | undefined {
+  const isBrowser = useIsBrowser();
+  return useMemo(() => {
+    if (item.href && !item.linkUnlisted) {
+      return item.href;
+    }
+    // In these cases, it's not necessary to render a fallback
+    // We skip the "findFirstCategoryLink" computation
+    if (isBrowser || !item.collapsible) {
+      return undefined;
+    }
+    return findFirstSidebarItemLink(item);
+  }, [item, isBrowser]);
+}
+
+function CollapseButton({
+  collapsed,
+  categoryLabel,
+  onClick,
+}: {
+  collapsed: boolean;
+  categoryLabel: string;
+  onClick: ComponentProps<'button'>['onClick'];
+}) {
+  return (
+    <button
+      aria-label={
+        collapsed
+          ? translate(
+              {
+                id: 'theme.DocSidebarItem.expandCategoryAriaLabel',
+                message: "Expand sidebar category '{label}'",
+                description: 'The ARIA label to expand the sidebar category',
+              },
+              { label: categoryLabel }
+            )
+          : translate(
+              {
+                id: 'theme.DocSidebarItem.collapseCategoryAriaLabel',
+                message: "Collapse sidebar category '{label}'",
+                description: 'The ARIA label to collapse the sidebar category',
+              },
+              { label: categoryLabel }
+            )
+      }
+      aria-expanded={!collapsed}
+      type="button"
+      className="clean-btn menu__caret"
+      onClick={onClick}
+    />
+  );
+}
+
+function CategoryLinkLabel({
+  label,
+  isRootCategory,
+  customProps,
+}: {
+  label: string;
+  isRootCategory: boolean;
+  customProps?: CustomSidebarProps;
+}) {
+  return (
+    <>
+      <span
+        title={label}
+        className={clsx(styles.categoryLinkLabel, {
+          [styles.categoryLinkLabelRoot]: isRootCategory,
+          [styles.categoryLinkLabelNested]: !isRootCategory,
+        })}
+      >
+        {label}
+      </span>
+      {customProps?.plan === 'pro' && <ProBadge />}
+      {customProps?.badgeType && <StatusBadge type={customProps.badgeType} />}
+    </>
+  );
+}
+
+export default function DocSidebarItemCategory(
+  props: WithCustomProps<Props>
+): ReactNode {
+  const visibleChildren = useVisibleSidebarItems(
+    props.item.items,
+    props.activePath
+  );
+  if (visibleChildren.length === 0) {
+    return <DocSidebarItemCategoryEmpty {...props} />;
+  } else {
+    return <DocSidebarItemCategoryCollapsible {...props} />;
+  }
+}
+
+function isCategoryWithHref(
+  category: PropSidebarItemCategory
+): category is PropSidebarItemCategory & { href: string } {
+  return typeof category.href === 'string';
+}
+
+// If a category doesn't have any visible children, we render it as a link
+function DocSidebarItemCategoryEmpty({
+  item,
+  ...props
+}: WithCustomProps<Props>): ReactNode {
+  // If the category has no link, we don't render anything
+  // It's not super useful to render a category you can't open nor click
+  if (!isCategoryWithHref(item)) {
+    return null;
+  }
+  // We remove props that don't make sense for a link and forward the rest
+  const {
+    type: _type,
+    collapsed: _collapsed,
+    collapsible: _collapsible,
+    items: _items,
+    linkUnlisted: _linkUnlisted,
+    ...forwardableProps
+  } = item;
+  const linkItem: PropSidebarItemLink = {
+    type: 'link',
+    ...forwardableProps,
+  };
+  return <DocSidebarItemLink item={linkItem} {...props} />;
+}
+
+function DocSidebarItemCategoryCollapsible({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: WithCustomProps<Props>): ReactNode {
+  const { items, label, collapsible, className, href, customProps } = item;
+  const {
+    docs: {
+      sidebar: { autoCollapseCategories },
+    },
+  } = useThemeConfig();
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
+
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isCurrentPage = isSamePath(href, activePath);
+
+  // Root categories (level === 1) are always expanded and non-collapsible
+  const isRootCategory = level === 1;
+
+  const { collapsed, setCollapsed } = useCollapsible({
+    // Root categories (level === 1) are always expanded
+    // Level 2 categories respect the collapsed prop from sidebars.ts
+    // Deeper nested categories (level > 2) are collapsed by default, unless they are active
+    initialState: () => {
+      if (isRootCategory) {
+        return false; // Always expanded for root categories
+      }
+      if (!collapsible) {
+        return false;
+      }
+      // Level 2 categories: respect the collapsed prop from sidebars.ts
+      if (level === 2) {
+        return item.collapsed ?? false; // Use sidebar config, default to open
+      }
+      // Deeper nested categories (level > 2): only expand if active, otherwise collapse
+      return isActive ? false : true;
+    },
+  });
+
+  const { expandedItem, setExpandedItem } = useDocSidebarItemsExpandedState();
+  // Use this instead of `setCollapsed`, because it is also reactive
+  const updateCollapsed = (toCollapsed: boolean = !collapsed) => {
+    // Root categories cannot be collapsed
+    if (isRootCategory) {
+      return;
+    }
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  };
+
+  // Only auto-expand for nested categories, not root
+  // We need to call the hook unconditionally (React rules), but make it a no-op for root categories
+  useAutoExpandActiveCategory({
+    isActive: isActive && !isRootCategory,
+    collapsed: isRootCategory ? false : collapsed,
+    updateCollapsed: isRootCategory ? () => {} : updateCollapsed,
+    activePath,
+  });
+
+  useEffect(() => {
+    // Root categories should never collapse - always keep them expanded
+    if (isRootCategory) {
+      setCollapsed(false);
+      return;
+    }
+    // Auto-collapse when other categories expand (only if autoCollapseCategories is enabled)
+    if (
+      collapsible &&
+      expandedItem != null &&
+      expandedItem !== index &&
+      autoCollapseCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [
+    collapsible,
+    expandedItem,
+    index,
+    setCollapsed,
+    autoCollapseCategories,
+    isRootCategory,
+  ]);
+
+  const handleItemClick: ComponentProps<'a'>['onClick'] = (e) => {
+    onItemClick?.(item);
+    // Root categories cannot be collapsed, so skip collapse logic
+    if (isRootCategory) {
+      return;
+    }
+    if (collapsible) {
+      if (href) {
+        // When already on the category's page, we collapse it
+        // We don't use "isActive" because it would collapse the
+        // category even when we browse a children element
+        // See https://github.com/facebook/docusaurus/issues/11213
+        if (isCurrentPage) {
+          e.preventDefault();
+          updateCollapsed();
+        } else {
+          // When navigating to a new category, we always expand
+          // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
+          updateCollapsed(false);
+        }
+      } else {
+        e.preventDefault();
+        updateCollapsed();
+      }
+    }
+  };
+
+  // Dynamic indent for nested categories (level 3+)
+  const nestedIndent = level >= 3 ? (level - 2) * 0.05 : 0;
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+          [styles.rootCategoryContainer]: isRootCategory,
+        },
+        className
+      )}
+    >
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage,
+        })}
+      >
+        <Link
+          className={clsx(styles.categoryLink, 'menu__link', {
+            [styles.categoryLinkRoot]: isRootCategory,
+            'menu__link--sublist': collapsible && !isRootCategory,
+            'menu__link--sublist-caret':
+              !href && collapsible && !isRootCategory,
+            'menu__link--active': isActive,
+          })}
+          style={
+            nestedIndent > 0
+              ? { paddingLeft: `${nestedIndent + 0.5}rem` }
+              : undefined
+          }
+          onClick={handleItemClick}
+          aria-current={isCurrentPage ? 'page' : undefined}
+          role={collapsible && !href && !isRootCategory ? 'button' : undefined}
+          aria-expanded={
+            collapsible && !href && !isRootCategory ? !collapsed : undefined
+          }
+          href={
+            collapsible && !isRootCategory
+              ? (hrefWithSSRFallback ?? '#')
+              : hrefWithSSRFallback
+          }
+          {...props}
+        >
+          {/* Only show collapse button for nested categories (not root) */}
+          {href && collapsible && !isRootCategory && (
+            <CollapseButton
+              collapsed={collapsed}
+              categoryLabel={label}
+              onClick={(e) => {
+                e.preventDefault();
+                updateCollapsed();
+              }}
+            />
+          )}
+          <CategoryLinkLabel
+            label={label}
+            isRootCategory={isRootCategory}
+            customProps={customProps}
+          />
+        </Link>
+      </div>
+
+      <Collapsible
+        lazy
+        as="ul"
+        className={clsx('menu__list', isRootCategory && styles.categoryList)}
+        collapsed={collapsed}
+      >
+        <DocSidebarItems
+          items={items}
+          tabIndex={collapsed ? -1 : 0}
+          onItemClick={onItemClick}
+          activePath={activePath}
+          level={level + 1}
+        />
+      </Collapsible>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/Category/styles.module.css

@@ -0,0 +1,119 @@
+.categoryLink {
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  padding-left: 0;
+  gap: 0.1;
+  position: relative;
+}
+
+.categoryLink::after {
+  order: -1;
+  margin-left: 1rem;
+  min-width: 1rem;
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+  background-size: contain;
+}
+
+.categoryLinkLabel {
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  color: var(--color-text-primary);
+}
+
+.categoryLinkRoot {
+  padding-left: 1.5rem;
+}
+
+/* Root category container with full-height border */
+.rootCategoryContainer {
+  position: relative;
+  margin-left: 1rem;
+}
+
+/* Circle outline at the top */
+.rootCategoryContainer::before {
+  content: '';
+  position: absolute;
+  left: calc(0.5rem - 4px);
+  top: 0.85rem;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  border: 1px solid var(--ifm-toc-border-color);
+  background-color: var(--ifm-background-color);
+  z-index: 2;
+  pointer-events: none;
+  transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+/* Circle outline turns blue on hover */
+.rootCategoryContainer:has(> :global(.menu__list-item-collapsible) > :global(.menu__link):hover)::before {
+  border-color: var(--ifm-color-primary-light);
+}
+
+/* Circle outline turns blue when category has active item */
+.rootCategoryContainer:has(:global(.menu__link--active))::before {
+  border-color: var(--ifm-color-primary-light);
+}
+
+/* Vertical line starting from the circle */
+.rootCategoryContainer::after {
+  content: '';
+  position: absolute;
+  left: 0.5rem;
+  top: calc(0.85rem + 8px);
+  bottom: 0;
+  width: 1px;
+  background-color: var(--ifm-toc-border-color);
+  z-index: 1;
+  pointer-events: none;
+}
+
+.categoryLinkLabelRoot {
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.categoryLinkLabelNested {
+  font-size: 0.85rem;
+  font-weight: 500;
+}
+
+.categoryList {
+  position: relative;
+  margin-left: 0;
+  padding-left: 0;
+}
+
+/* Reset margin for nested lists inside root category */
+.categoryList :global(.menu__list) {
+  margin-left: 0;
+  padding-left: 0;
+}
+
+/* Border indicator on nested items only (not on root category link itself) */
+.rootCategoryContainer .categoryList :global(.menu__link) {
+  position: relative;
+}
+
+.rootCategoryContainer .categoryList :global(.menu__link)::before {
+  content: '';
+  position: absolute;
+  left: 0.5rem;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: transparent;
+  z-index: 2;
+  transition: background-color 0.15s ease;
+}
+
+.rootCategoryContainer .categoryList :global(.menu__link:hover)::before {
+  background-color: var(--ifm-color-primary-light);
+}

package/src/theme/DocSidebarItem/Link/index.tsx

@@ -0,0 +1,85 @@
+import React, { type ReactNode } from 'react';
+import clsx from 'clsx';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+import { isActiveSidebarItem } from '@docusaurus/plugin-content-docs/client';
+import Link from '@docusaurus/Link';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/Icon/ExternalLink';
+import type { Props } from '@theme/DocSidebarItem/Link';
+import ProBadge from '@/components/ProBadge/ProBadge';
+import StatusBadge from '@/components/StatusBadge/StatusBadge';
+import type { WithCustomProps } from '@/types/sidebar';
+
+import styles from './styles.module.css';
+
+function LinkLabel({ label }: { label: string }) {
+  return (
+    <span title={label} className={styles.linkLabel}>
+      {label}
+    </span>
+  );
+}
+
+export default function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index: _index,
+  ...props
+}: WithCustomProps<Props>): ReactNode {
+  const { href, label, className, autoAddBaseUrl, customProps } = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isInternalLink = isInternalUrl(href);
+
+  const isLink = item.type === 'link';
+
+  // Dynamic indent for nested items (level 3+)
+  const nestedIndent = level >= 3 ? (level - 2) * 0.05 : 0;
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className
+      )}
+      key={label}
+    >
+      <Link
+        className={clsx(
+          'menu__link',
+          styles.menuLink,
+          !isInternalLink && styles.menuExternalLink,
+          {
+            'menu__link--active': isActive,
+          }
+        )}
+        style={
+          nestedIndent > 0
+            ? { paddingLeft: `${nestedIndent + 2.5}rem` }
+            : undefined
+        }
+        autoAddBaseUrl={autoAddBaseUrl}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalLink && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}
+      >
+        <LinkLabel label={label} />
+        {!isInternalLink && <IconExternalLink />}
+        {isLink && (
+          <>
+            {customProps?.plan === 'pro' && <ProBadge />}
+            {customProps?.badgeType && (
+              <StatusBadge type={customProps.badgeType} />
+            )}
+          </>
+        )}
+      </Link>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/Link/styles.module.css

@@ -0,0 +1,18 @@
+.menuExternalLink {
+  align-items: center;
+}
+
+.menuLink {
+  padding-left: 2rem;
+  padding-top: 0.25rem;
+  padding-bottom: 0.25rem;
+}
+
+.linkLabel {
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  font-size: 0.8rem;
+}

package/src/theme/TOC/index.tsx

@@ -0,0 +1,25 @@
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import TOCItems from '@theme/TOCItems';
+import type {Props} from '@theme/TOC';
+
+import styles from './styles.module.css';
+import TWGBadge from '@/components/TWGBadge/TWGBadge';
+
+// Using a custom className
+// This prevents TOCInline/TOCCollapsible getting highlighted by mistake
+const LINK_CLASS_NAME = 'table-of-contents__link toc-highlight';
+const LINK_ACTIVE_CLASS_NAME = 'table-of-contents__link--active';
+
+export default function TOC({className, ...props}: Props): ReactNode {
+  return (
+    <div className={clsx(styles.tableOfContents, 'thin-scrollbar', className)}>
+      <TOCItems
+        {...props}
+        linkClassName={LINK_CLASS_NAME}
+        linkActiveClassName={LINK_ACTIVE_CLASS_NAME}
+      />
+      <TWGBadge visibleOnLarge={true} />
+    </div>
+  );
+}

package/src/theme/TOC/styles.module.css

@@ -0,0 +1,16 @@
+.tableOfContents {
+  max-height: calc(100vh - (var(--ifm-navbar-height) + 2rem));
+  overflow-y: auto;
+  position: sticky;
+  top: calc(var(--ifm-navbar-height) + 1rem);
+}
+
+@media (max-width: 996px) {
+  .tableOfContents {
+    display: none;
+  }
+
+  .docItemContainer {
+    padding: 0 0.3rem;
+  }
+}

package/src/types/sidebar.ts

@@ -0,0 +1,23 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+export interface CustomSidebarProps {
+  plan?: 'pro';
+  badgeType?: 'planned' | 'new';
+}
+
+export type AddCustomProps<T> = T extends readonly (infer U)[]
+  ? Array<AddCustomProps<U>>
+  : T extends object
+    ? Omit<{ [K in keyof T]: AddCustomProps<T[K]> }, 'customProps'> & {
+        customProps?: CustomSidebarProps;
+      }
+    : T;
+
+export type TypedSidebarsConfig = AddCustomProps<SidebarsConfig>;
+
+export type WithCustomProps<Props extends { item: unknown }> = Omit<
+  Props,
+  'item'
+> & {
+  item: AddCustomProps<Props['item']> & Props['item'];
+};