@eventcatalog/core 2.21.5 → 2.23.0

package/eventcatalog/src/components/TreeView/index.tsx

@@ -0,0 +1,328 @@
+import React, { useCallback, useEffect } from 'react';
+import classes from './styles.module.css';
+import { useSlots } from './useSlots';
+import { ChevronDownIcon, ChevronRightIcon } from 'lucide-react';
+
+// ----------------------------------------------------------------------------
+// Context
+
+const RootContext = React.createContext<{
+  // We cache the expanded state of tree items so we can preserve the state
+  // across remounts. This is necessary because we unmount tree items
+  // when their parent is collapsed.
+  expandedStateCache: React.RefObject<Map<string, boolean> | null>;
+}>({
+  expandedStateCache: { current: new Map() },
+});
+
+const ItemContext = React.createContext<{
+  level: number;
+  isExpanded: boolean;
+}>({
+  level: 1,
+  isExpanded: false,
+});
+
+// ----------------------------------------------------------------------------
+// TreeView
+
+export type TreeViewProps = {
+  'aria-label'?: React.AriaAttributes['aria-label'];
+  'aria-labelledby'?: React.AriaAttributes['aria-labelledby'];
+  children: React.ReactNode;
+  flat?: boolean;
+  truncate?: boolean;
+  style?: React.CSSProperties;
+};
+
+/* Size of toggle icon in pixels. */
+const TOGGLE_ICON_SIZE = 12;
+
+const Root: React.FC<TreeViewProps> = ({
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledby,
+  children,
+  flat,
+  truncate = true,
+  style,
+}) => {
+  const containerRef = React.useRef<HTMLUListElement>(null);
+  const mouseDownRef = React.useRef<boolean>(false);
+
+  const onMouseDown = useCallback(() => {
+    mouseDownRef.current = true;
+  }, []);
+
+  useEffect(() => {
+    function onMouseUp() {
+      mouseDownRef.current = false;
+    }
+    document.addEventListener('mouseup', onMouseUp);
+    return () => {
+      document.removeEventListener('mouseup', onMouseUp);
+    };
+  }, []);
+
+  const expandedStateCache = React.useRef<Map<string, boolean> | null>(null);
+
+  if (expandedStateCache.current === null) {
+    expandedStateCache.current = new Map();
+  }
+
+  return (
+    <RootContext.Provider
+      value={{
+        expandedStateCache,
+      }}
+    >
+      <ul
+        ref={containerRef}
+        role="tree"
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledby}
+        data-omit-spacer={flat}
+        data-truncate-text={truncate || false}
+        onMouseDown={onMouseDown}
+        className={classes.TreeViewRootUlStyles}
+        style={style}
+      >
+        {children}
+      </ul>
+    </RootContext.Provider>
+  );
+};
+
+Root.displayName = 'TreeView';
+
+// ----------------------------------------------------------------------------
+// TreeView.Item
+
+export type TreeViewItemProps = {
+  id: string;
+  children: React.ReactNode;
+  current?: boolean;
+  defaultExpanded?: boolean;
+  onSelect?: (event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;
+};
+
+const Item = React.forwardRef<HTMLElement, TreeViewItemProps>(
+  ({ id: itemId, current: isCurrentItem = false, defaultExpanded, onSelect, children }, ref) => {
+    const [slots, rest] = useSlots(children, {
+      leadingVisual: LeadingVisual,
+    });
+    const { expandedStateCache } = React.useContext(RootContext);
+
+    const [isExpanded, setIsExpanded] = React.useState(
+      expandedStateCache.current?.get(itemId) ?? defaultExpanded ?? isCurrentItem
+    );
+    const { level } = React.useContext(ItemContext);
+    const { hasSubTree, subTree, childrenWithoutSubTree } = useSubTree(rest);
+    const [isFocused, setIsFocused] = React.useState(false);
+
+    // Set the expanded state and cache it
+    const setIsExpandedWithCache = React.useCallback(
+      (newIsExpanded: boolean) => {
+        setIsExpanded(newIsExpanded);
+        expandedStateCache.current?.set(itemId, newIsExpanded);
+      },
+      [itemId, setIsExpanded, expandedStateCache]
+    );
+
+    // Expand or collapse the subtree
+    const toggle = React.useCallback(
+      (event?: React.MouseEvent | React.KeyboardEvent) => {
+        setIsExpandedWithCache(!isExpanded);
+        event?.stopPropagation();
+      },
+      [isExpanded, setIsExpandedWithCache]
+    );
+
+    const handleKeyDown = React.useCallback(
+      (event: React.KeyboardEvent<HTMLElement>) => {
+        switch (event.key) {
+          case 'Enter':
+          case ' ':
+            if (onSelect) {
+              onSelect(event);
+            } else {
+              toggle(event);
+            }
+            event.stopPropagation();
+            break;
+          case 'ArrowRight':
+            // Ignore if modifier keys are pressed
+            if (event.altKey || event.metaKey) return;
+            event.preventDefault();
+            event.stopPropagation();
+            setIsExpandedWithCache(true);
+            break;
+          case 'ArrowLeft':
+            // Ignore if modifier keys are pressed
+            if (event.altKey || event.metaKey) return;
+            event.preventDefault();
+            event.stopPropagation();
+            setIsExpandedWithCache(false);
+            break;
+        }
+      },
+      [onSelect, setIsExpandedWithCache, toggle]
+    );
+
+    return (
+      <ItemContext.Provider
+        value={{
+          level: level + 1,
+          isExpanded,
+        }}
+      >
+        <li
+          className={classes.TreeViewItem}
+          ref={ref as React.ForwardedRef<HTMLLIElement>}
+          tabIndex={0}
+          id={itemId}
+          role="treeitem"
+          aria-level={level}
+          aria-expanded={isExpanded}
+          aria-current={isCurrentItem ? 'true' : undefined}
+          aria-selected={isFocused ? 'true' : 'false'}
+          onKeyDown={handleKeyDown}
+          onFocus={(event) => {
+            // Scroll the first child into view when the item receives focus
+            event.currentTarget.firstElementChild?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+
+            // Set the focused state
+            setIsFocused(true);
+
+            // Prevent focus event from bubbling up to parent items
+            event.stopPropagation();
+          }}
+          onBlur={() => setIsFocused(false)}
+          onClick={(event) => {
+            if (onSelect) {
+              onSelect(event);
+              // if has children open them too
+              if (hasSubTree) {
+                toggle(event);
+              }
+            } else {
+              toggle(event);
+            }
+            event.stopPropagation();
+          }}
+          onAuxClick={(event) => {
+            if (onSelect && event.button === 1) {
+              onSelect(event);
+            }
+            event.stopPropagation();
+          }}
+        >
+          <div
+            className={classes.TreeViewItemContainer}
+            style={{
+              // @ts-ignore CSS custom property
+              '--level': level,
+            }}
+          >
+            <div style={{ gridArea: 'spacer', display: 'flex' }}>{/* <LevelIndicatorLines level={level} /> */}</div>
+
+            <div className={classes.TreeViewItemContent}>
+              {slots.leadingVisual}
+              <span className={classes.TreeViewItemContentText}>{childrenWithoutSubTree}</span>
+            </div>
+            {hasSubTree ? (
+              <div
+                className={[classes.TreeViewItemToggle, classes.TreeViewItemToggleHover, classes.TreeViewItemToggleEnd].join(' ')}
+                onClick={(event) => {
+                  if (onSelect) {
+                    toggle(event);
+                  }
+                }}
+              >
+                {isExpanded ? <ChevronDownIcon size={TOGGLE_ICON_SIZE} /> : <ChevronRightIcon size={TOGGLE_ICON_SIZE} />}
+              </div>
+            ) : null}
+          </div>
+          {subTree}
+        </li>
+      </ItemContext.Provider>
+    );
+  }
+);
+
+Item.displayName = 'TreeView.Item';
+
+// ----------------------------------------------------------------------------
+// TreeView.SubTree
+
+export type TreeViewSubTreeProps = {
+  children?: React.ReactNode;
+};
+
+const SubTree: React.FC<TreeViewSubTreeProps> = ({ children }) => {
+  const { isExpanded } = React.useContext(ItemContext);
+  const ref = React.useRef<HTMLUListElement>(null);
+
+  if (!isExpanded) {
+    return null;
+  }
+
+  return (
+    <ul
+      role="group"
+      style={{
+        listStyle: 'none',
+        padding: 0,
+        margin: 0,
+      }}
+      ref={ref}
+    >
+      {children}
+    </ul>
+  );
+};
+
+SubTree.displayName = 'TreeView.SubTree';
+
+function useSubTree(children: React.ReactNode) {
+  return React.useMemo(() => {
+    const subTree = React.Children.toArray(children).find((child) => React.isValidElement(child) && child.type === SubTree);
+
+    const childrenWithoutSubTree = React.Children.toArray(children).filter(
+      (child) => !(React.isValidElement(child) && child.type === SubTree)
+    );
+
+    return {
+      subTree,
+      childrenWithoutSubTree,
+      hasSubTree: Boolean(subTree),
+    };
+  }, [children]);
+}
+
+// ----------------------------------------------------------------------------
+// TreeView.LeadingVisual
+
+export type TreeViewLeadingVisualProps = {
+  children: React.ReactNode | ((props: { isExpanded: boolean }) => React.ReactNode);
+};
+
+const LeadingVisual: React.FC<TreeViewLeadingVisualProps> = (props) => {
+  const { isExpanded } = React.useContext(ItemContext);
+  const children = typeof props.children === 'function' ? props.children({ isExpanded }) : props.children;
+  return (
+    <div className={classes.TreeViewItemVisual} aria-hidden={true}>
+      {children}
+    </div>
+  );
+};
+
+LeadingVisual.displayName = 'TreeView.LeadingVisual';
+
+// ----------------------------------------------------------------------------
+// Export
+
+export const TreeView = Object.assign(Root, {
+  Item,
+  SubTree,
+  LeadingVisual,
+});

package/eventcatalog/src/components/TreeView/styles.module.css

@@ -0,0 +1,264 @@
+.TreeViewRootUlStyles {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+
+  /*
+   * WARNING: This is a performance optimization.
+   *
+   * We define styles for the tree items at the root level of the tree
+   * to avoid recomputing the styles for each item when the tree updates.
+   * We're sacrificing maintainability for performance because TreeView
+   * needs to be performant enough to handle large trees (thousands of items).
+   *
+   * This is intended to be a temporary solution until we can improve the
+   * performance of our styling patterns.
+   *
+   * Do NOT copy this pattern without understanding the tradeoffs.
+   */
+  .TreeViewItem {
+    outline: none;
+
+    &:focus-visible > div,
+    &.focus-visible > div {
+      box-shadow: var(--boxShadow-thick) /* var(--fgColor-accent) */ slategray;
+
+      @media (forced-colors: active) {
+        outline: 2px solid HighlightText;
+        outline-offset: -2;
+      }
+    }
+
+    &[data-has-leading-action] {
+      --has-leading-action: 1;
+    }
+  }
+
+  .TreeViewItemContainer {
+    --level: 1;
+    --toggle-width: 1rem;
+    --min-item-height: 2rem;
+
+    position: relative;
+    display: grid;
+    width: 100%;
+    font-size: var(--text-body-size-medium);
+    color: var(--fgColor-default);
+    cursor: pointer;
+    border-radius: var(--borderRadius-medium);
+    grid-template-columns: var(--spacer-width) var(--leading-action-width) 1fr var(--toggle-width);
+    grid-template-areas: 'spacer leadingAction content toggle';
+
+    --leading-action-width: calc(var(--has-leading-action, 0) * 1.5rem);
+    --spacer-width: calc(calc(var(--level) - 1) * (var(--toggle-width) / 2));
+
+    &:hover {
+      background-color: var(--control-transparent-bgColor-hover);
+
+      @media (forced-colors: active) {
+        outline: 2px solid transparent;
+        outline-offset: -2px;
+      }
+    }
+
+    @media (pointer: coarse) {
+      --toggle-width: 1.5rem;
+      --min-item-height: 2.75rem;
+    }
+
+    &:has(.TreeViewItemSkeleton):hover {
+      cursor: default;
+      background-color: transparent;
+
+      @media (forced-colors: active) {
+        outline: none;
+      }
+    }
+  }
+
+  &:where([data-omit-spacer='true']) .TreeViewItemContainer {
+    grid-template-columns: 0 0 1fr 0;
+  }
+
+  .TreeViewItem[aria-current='true'] > .TreeViewItemContainer {
+    background-color: var(--control-transparent-bgColor-selected);
+
+    /* Current item indicator */
+    /* stylelint-disable-next-line selector-max-specificity */
+    &::after {
+      position: absolute;
+      top: calc(50% - var(--base-size-12));
+      left: calc(-1 * var(--base-size-8));
+      width: 0.25rem;
+      height: 1.5rem;
+      content: '';
+
+      /*
+       * Use fgColor accent for consistency across all themes. Using the "correct" variable,
+       * --bgColor-accent-emphasis, causes vrt failures for dark high contrast mode
+       */
+      /* stylelint-disable-next-line primer/colors */
+      background-color: var(--fgColor-accent);
+      border-radius: var(--borderRadius-medium);
+
+      @media (forced-colors: active) {
+        background-color: HighlightText;
+      }
+    }
+  }
+
+  .TreeViewItemToggle {
+    display: flex;
+    height: 100%;
+
+    /* The toggle should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc(var(--min-item-height) / 2 - var(--base-size-12) / 2);
+    color: var(--fgColor-muted);
+    grid-area: toggle;
+    justify-content: center;
+    align-items: flex-start;
+  }
+
+  .TreeViewItemToggleHover:hover {
+    background-color: var(--control-transparent-bgColor-hover);
+  }
+
+  .TreeViewItemToggleEnd {
+    border-top-left-radius: var(--borderRadius-medium);
+    border-bottom-left-radius: var(--borderRadius-medium);
+  }
+
+  .TreeViewItemContent {
+    display: flex;
+    height: 100%;
+    padding: 0 var(--base-size-8);
+
+    /* The dynamic top and bottom padding to maintain the minimum item height for single line items */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    /* stylelint-disable-next-line primer/spacing */
+    padding-bottom: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    line-height: var(--custom-line-height, var(--text-body-lineHeight-medium, 1.4285));
+    grid-area: content;
+    gap: var(--stack-gap-condensed);
+  }
+
+  .TreeViewItemContentText {
+    flex: 1 1 auto;
+    width: 0;
+  }
+
+  &:where([data-truncate-text='true']) .TreeViewItemContentText {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &:where([data-truncate-text='false']) .TreeViewItemContentText {
+    word-break: break-word;
+  }
+
+  .TreeViewItemVisual {
+    display: flex;
+
+    /* The visual icons should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    height: var(--custom-line-height, 1.3rem);
+    color: var(--fgColor-muted);
+    align-items: center;
+  }
+
+  .TreeViewItemLeadingAction {
+    display: flex;
+    color: var(--fgColor-muted);
+    grid-area: leadingAction;
+
+    & > button {
+      flex-shrink: 1;
+    }
+  }
+
+  .TreeViewItemLevelLine {
+    width: 100%;
+    height: 100%;
+
+    /*
+     * On devices without hover, the nesting indicator lines
+     * appear at all times.
+     */
+    border-color: var(--borderColor-muted);
+    border-right: var(--borderWidth-thin) solid;
+  }
+
+  /*
+   * On devices with :hover support, the nesting indicator lines
+   * fade in when the user mouses over the entire component,
+   * or when there's focus inside the component. This makes
+   * sure the component remains simple when not in use.
+   */
+  @media (hover: hover) {
+    .TreeViewItemLevelLine {
+      border-color: transparent;
+    }
+
+    &:hover .TreeViewItemLevelLine,
+    &:focus-within .TreeViewItemLevelLine {
+      border-color: var(--borderColor-muted);
+    }
+  }
+
+  .TreeViewDirectoryIcon {
+    display: grid;
+    color: var(--treeViewItem-leadingVisual-iconColor-rest);
+  }
+
+  .TreeViewVisuallyHidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    /* stylelint-disable-next-line primer/spacing */
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  }
+}
+
+.TreeViewSkeletonItemContainerStyle {
+  display: flex;
+  align-items: center;
+  column-gap: 0.5rem;
+  height: 2rem;
+
+  @media (pointer: coarse) {
+    height: 2.75rem;
+  }
+
+  &:nth-of-type(5n + 1) {
+    --tree-item-loading-width: 67%;
+  }
+
+  &:nth-of-type(5n + 2) {
+    --tree-item-loading-width: 47%;
+  }
+
+  &:nth-of-type(5n + 3) {
+    --tree-item-loading-width: 73%;
+  }
+
+  &:nth-of-type(5n + 4) {
+    --tree-item-loading-width: 64%;
+  }
+
+  &:nth-of-type(5n + 5) {
+    --tree-item-loading-width: 50%;
+  }
+}
+
+.TreeItemSkeletonTextStyles {
+  width: var(--tree-item-loading-width, 67%);
+}

package/eventcatalog/src/components/TreeView/useSlots.ts

@@ -0,0 +1,95 @@
+import React from 'react';
+// import {warning} from '../utils/warning'
+
+// slot config allows 2 options:
+// 1. Component to match, example: { leadingVisual: LeadingVisual }
+type ComponentMatcher = React.ElementType<Props>;
+// 2. Component to match + a test function, example: { blockDescription: [Description, props => props.variant === 'block'] }
+type ComponentAndPropsMatcher = [ComponentMatcher, (props: Props) => boolean];
+
+export type SlotConfig = Record<string, ComponentMatcher | ComponentAndPropsMatcher>;
+
+// We don't know what the props are yet, we set them later based on slot config
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Props = any;
+
+type SlotElements<Config extends SlotConfig> = {
+  [Property in keyof Config]: SlotValue<Config, Property>;
+};
+
+type SlotValue<Config, Property extends keyof Config> = Config[Property] extends React.ElementType // config option 1
+  ? React.ReactElement<React.ComponentPropsWithoutRef<Config[Property]>, Config[Property]>
+  : Config[Property] extends readonly [
+        infer ElementType extends React.ElementType, // config option 2, infer array[0] as component
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        infer _testFn, // even though we don't use testFn, we need to infer it to support types for slots.*.props
+      ]
+    ? React.ReactElement<React.ComponentPropsWithoutRef<ElementType>, ElementType>
+    : never; // useful for narrowing types, third option is not possible
+
+/**
+ * Extract components from `children` so we can render them in different places,
+ * allowing us to implement components with SSR-compatible slot APIs.
+ * Note: We can only extract direct children, not nested ones.
+ */
+export function useSlots<Config extends SlotConfig>(
+  children: React.ReactNode,
+  config: Config
+): [Partial<SlotElements<Config>>, React.ReactNode[]] {
+  // Object mapping slot names to their elements
+  const slots: Partial<SlotElements<Config>> = mapValues(config, () => undefined);
+
+  // Array of elements that are not slots
+  const rest: React.ReactNode[] = [];
+
+  const keys = Object.keys(config) as Array<keyof Config>;
+  const values = Object.values(config);
+
+  // eslint-disable-next-line github/array-foreach
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) {
+      rest.push(child);
+      return;
+    }
+
+    const index = values.findIndex((value) => {
+      if (Array.isArray(value)) {
+        const [component, testFn] = value;
+        return child.type === component && testFn(child.props);
+      } else {
+        return child.type === value;
+      }
+    });
+
+    // If the child is not a slot, add it to the `rest` array
+    if (index === -1) {
+      rest.push(child);
+      return;
+    }
+
+    const slotKey = keys[index];
+
+    // If slot is already filled, ignore duplicates
+    if (slots[slotKey]) {
+      // warning(true, `Found duplicate "${String(slotKey)}" slot. Only the first will be rendered.`)
+      return;
+    }
+
+    // If the child is a slot, add it to the `slots` object
+
+    slots[slotKey] = child as SlotValue<Config, keyof Config>;
+  });
+
+  return [slots, rest];
+}
+
+/** Map the values of an object */
+function mapValues<T extends Record<string, unknown>, V>(obj: T, fn: (value: T[keyof T]) => V) {
+  return Object.keys(obj).reduce(
+    (result, key: keyof T) => {
+      result[key] = fn(obj[key]);
+      return result;
+    },
+    {} as Record<keyof T, V>
+  );
+}

package/eventcatalog/src/content/config.ts

@@ -269,6 +269,7 @@ const users = defineCollection({
     ownedCommands: z.array(reference('commands')).optional(),
     ownedQueries: z.array(reference('queries')).optional(),
     associatedTeams: z.array(reference('teams')).optional(),
+    pathToFile: z.string().optional(),
   }),
 });
 
@@ -288,6 +289,7 @@ const teams = defineCollection({
     ownedDomains: z.array(reference('domains')).optional(),
     ownedServices: z.array(reference('services')).optional(),
     ownedEvents: z.array(reference('events')).optional(),
+    pathToFile: z.string().optional(),
   }),
 });