zudoku 0.0.2-dev.0

package/src/app/ui/Card.tsx

@@ -0,0 +1,82 @@
+import * as React from "react";
+import { cn } from "../util/cn.js";
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "rounded-xl border bg-card text-card-foreground shadow",
+      className,
+    )}
+    {...props}
+  />
+));
+Card.displayName = "Card";
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col space-y-1.5 p-6", className)}
+    {...props}
+  />
+));
+CardHeader.displayName = "CardHeader";
+
+const CardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn("font-semibold leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+CardTitle.displayName = "CardTitle";
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+CardDescription.displayName = "CardDescription";
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+));
+CardContent.displayName = "CardContent";
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+  />
+));
+CardFooter.displayName = "CardFooter";
+
+export {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+};

package/src/app/ui/Note.tsx

@@ -0,0 +1,58 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { cn } from "../util/cn.js";
+
+const noteVariants = cva(
+  "relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground",
+  {
+    variants: {
+      variant: {
+        default: "bg-background text-foreground",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+const Note = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof noteVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div
+    ref={ref}
+    role="alert"
+    className={cn(noteVariants({ variant }), className)}
+    {...props}
+  />
+));
+Note.displayName = "Alert";
+
+const NoteTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h5
+    ref={ref}
+    className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+    {...props}
+  />
+));
+NoteTitle.displayName = "AlertTitle";
+
+const NoteDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("text-sm [&_p]:leading-relaxed", className)}
+    {...props}
+  />
+));
+NoteDescription.displayName = "AlertDescription";
+
+export { Note, NoteDescription, NoteTitle };

package/src/app/util/MdxComponents.tsx

@@ -0,0 +1,70 @@
+import { MDXProvider } from "@mdx-js/react";
+import type { ComponentProps } from "react";
+
+import { Link } from "react-router-dom";
+import { Heading } from "../Heading.js";
+import { SyntaxHighlight } from "../components/SyntaxHighlight.js";
+import { Callout } from "../ui/Callout.js";
+import { cn } from "./cn.js";
+
+export type MdxComponentsType = ComponentProps<
+  typeof MDXProvider
+>["components"];
+
+export const MdxComponents = {
+  img: (props) => {
+    if (/\.(mp4|webm|mov|avi)$/.test(props.src ?? "")) {
+      return <video src={props.src} controls playsInline autoPlay loop />;
+    }
+    return <img {...props} className="rounded-md" />;
+  },
+  h1: ({ children, id }) => <Heading level={1} id={id} children={children} />,
+  h2: ({ children, id }) => <Heading level={2} id={id} children={children} />,
+  h3: ({ children, id }) => <Heading level={3} id={id} children={children} />,
+  h4: ({ children, id }) => <Heading level={4} id={id} children={children} />,
+  h5: ({ children, id }) => <Heading level={5} id={id} children={children} />,
+  h6: ({ children, id }) => <Heading level={6} id={id} children={children} />,
+  a: ({ href, ...props }) =>
+    href && !href.startsWith("http") ? (
+      <Link to={href} relative="path" {...props} />
+    ) : (
+      <a href={href} target="_blank" {...props} />
+    ),
+  Callout,
+  tip: (props) => <Callout type="tip" {...props} />,
+  info: (props) => <Callout type="info" {...props} />,
+  note: (props) => <Callout type="note" {...props} />,
+  caution: (props) => <Callout type="caution" {...props} />,
+  warning: (props) => <Callout type="caution" {...props} />,
+  danger: (props) => <Callout type="danger" {...props} />,
+
+  pre: ({ children }) => <>{children}</>,
+  code: ({ className, children, ...props }) => {
+    // `inline` provided by the rehype plugin, as react-markdown removed support for that
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const inline = (props as any).inline;
+
+    if (!inline) {
+      const match = className?.match(/language?-(\w+)/);
+
+      return (
+        <SyntaxHighlight
+          language={match?.[1] ?? "markup"}
+          className="rounded-xl overflow-x-auto p-4 border border-border dark:!bg-foreground/10 dark:border-transparent"
+          code={String(children).trim()}
+        />
+      );
+    }
+
+    return (
+      <code
+        className={cn(
+          className,
+          "font-mono border border-border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70",
+        )}
+      >
+        {children}
+      </code>
+    );
+  },
+} satisfies MdxComponentsType;

package/src/app/util/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/app/util/createWaitForNotify.ts

@@ -0,0 +1,18 @@
+export const createWaitForNotify = <T extends NonNullable<unknown>>() => {
+  const resolveMap = new Map<string, (value: T | PromiseLike<T>) => void>();
+
+  const waitFor = (id: string) =>
+    new Promise<T>((resolve) => {
+      resolveMap.set(id, resolve);
+    });
+
+  const notify = (id: string, data: T) => {
+    const resolveFn = resolveMap.get(id);
+    if (resolveFn) {
+      resolveFn(data);
+      resolveMap.delete(id);
+    }
+  };
+
+  return [waitFor, notify] as const;
+};

package/src/app/util/groupBy.ts

@@ -0,0 +1,24 @@
+type MapValuesToKeysIfAllowed<T> = {
+  [K in keyof T]: T[K] extends PropertyKey ? K : never;
+};
+type Filter<T> = MapValuesToKeysIfAllowed<T>[keyof T];
+
+export const groupBy = <
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends Record<PropertyKey, any>,
+  Key extends Filter<T>,
+>(
+  arr: T[],
+  key: Key,
+): Record<T[Key], T[]> =>
+  arr.reduce(
+    (accumulator, val) => {
+      const groupedKey = val[key];
+      if (!accumulator[groupedKey]) {
+        accumulator[groupedKey] = [];
+      }
+      accumulator[groupedKey].push(val);
+      return accumulator;
+    },
+    {} as Record<T[Key], T[]>,
+  );

package/src/app/util/joinPath.tsx

@@ -0,0 +1,10 @@
+export const joinPath = (
+  ...parts: Array<string | null | undefined | boolean>
+) => {
+  const cleanPath = parts
+    .filter((part): part is string => Boolean(part))
+    .map((part) => part.replace(/(^\/+|\/+$)/g, "")) // Strip leading and trailing slashes
+    .join("/");
+
+  return cleanPath ? `/${cleanPath}` : "";
+};

package/src/app/util/pastellize.ts

@@ -0,0 +1,25 @@
+const c2n = (c: string) =>
+  Math.abs(
+    isNaN(parseInt(c))
+      ? c.toLowerCase().charCodeAt(0) - 96
+      : isNaN(parseInt(c))
+        ? 0
+        : parseInt(c),
+  );
+const s2n = (s: string) =>
+  s.length > 1
+    ? parseInt(s.split("").reduce((a, c) => `${c2n(a) + c2n(c)}`))
+    : c2n(s);
+
+export const pastellize = (
+  s: string,
+  options: {
+    saturation?: number;
+    lightness?: number;
+  } = {},
+) => {
+  const hue = (3 * s2n(s) + 2 * s2n(s) + s2n(s)) % 360;
+  const { saturation = 75, lightness = 60 } = options;
+
+  return `${hue}deg ${saturation}% ${lightness}%`;
+};

package/src/app/util/slugify.ts

@@ -0,0 +1,3 @@
+import slugify from "slugify";
+
+export default slugify;

package/src/app/util/traverseNavigation.ts

@@ -0,0 +1,55 @@
+import { isPathItem } from "../components/navigation/util.js";
+import type {
+  NavigationCategory,
+  NavigationCategoryItem,
+  NavigationItem,
+} from "../core/DevPortalContext.js";
+import { joinPath } from "./joinPath.js";
+
+export type NavigationNode = NavigationCategoryItem | NavigationCategory;
+type Callback<T> = (
+  node: NavigationNode,
+  fullPath: string,
+  parentNodes: NavigationNode[],
+) => T | undefined;
+
+export const traverseNavigationNode = <T>(
+  node: NavigationNode,
+  callback: Callback<T>,
+  parentPath: string,
+  parentNodes: NavigationNode[] = [],
+): T | undefined => {
+  const newPath = isPathItem(node)
+    ? joinPath(parentPath, node.path)
+    : parentPath;
+  const result = callback(node, newPath, parentNodes);
+
+  if (result !== undefined) return result;
+
+  if ("children" in node && node.children) {
+    const newParentNodes = [...parentNodes, node];
+    for (const child of node.children) {
+      const childResult = traverseNavigationNode(
+        child,
+        callback,
+        newPath,
+        newParentNodes,
+      );
+      if (childResult !== undefined) return childResult;
+    }
+  }
+  return undefined;
+};
+
+export const traverseNavigation = <T>(
+  navItem: NavigationItem,
+  callback: Callback<T>,
+): T | undefined => {
+  if (navItem.categories) {
+    for (const category of navItem.categories) {
+      const result = traverseNavigationNode(category, callback, navItem.path);
+      if (result !== undefined) return result;
+    }
+  }
+  return undefined;
+};

package/src/app/util/useScrollToAnchor.ts

@@ -0,0 +1,38 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+import { useViewportAnchor } from "../components/context/ViewportAnchorContext.js";
+
+export const useScrollToAnchor = () => {
+  const location = useLocation();
+  const { setActiveAnchor } = useViewportAnchor();
+
+  useEffect(() => {
+    if (!location.hash) return;
+
+    const hash = location.hash.split("/")[0].slice(1);
+
+    const element = document.getElementById(decodeURIComponent(hash));
+    if (element) {
+      // on page navigation element might be in DOM but not yet scrollable, so wait for a frame
+      requestAnimationFrame(() => {
+        element.scrollIntoView();
+        requestIdleCallback(() => setActiveAnchor(hash));
+      });
+      return;
+    }
+
+    // on page load, the element might not be available yet
+    const observer = new MutationObserver((_mutations, obs) => {
+      const element = document.getElementById(decodeURIComponent(hash));
+      if (!element) return;
+
+      element.scrollIntoView();
+      requestIdleCallback(() => setActiveAnchor(hash));
+      obs.disconnect();
+    });
+
+    observer.observe(document.body, { childList: true, subtree: true });
+
+    return () => observer.disconnect();
+  }, [location.hash, setActiveAnchor]);
+};

package/src/app/util/useScrollToTop.ts

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+import { useLocation } from "react-router-dom";
+
+export const useScrollToTop = () => {
+  const location = useLocation();
+  const previousPath = useRef(location.pathname);
+
+  useEffect(() => {
+    if (previousPath.current === location.pathname) return;
+    window.scrollTo(0, 0);
+    previousPath.current = location.pathname;
+  }, [location.pathname]);
+};