zudoku 0.1.1-dev.18 → 0.1.1-dev.19

package/src/lib/ui/Button.tsx

@@ -0,0 +1,56 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../util/cn.js";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

package/src/lib/ui/Callout.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import {
+  AlertTriangleIcon,
+  InfoIcon,
+  LightbulbIcon,
+  ShieldAlertIcon,
+} from "../core/icons.js";
+import { cn } from "../util/cn.js";
+
+const stylesMap = {
+  note: {
+    border: "border-gray-300 dark:border-zinc-800",
+    bg: "bg-gray-100 dark:bg-zinc-800/50",
+    iconColor: "text-gray-600 dark:text-zinc-300",
+    titleColor: "text-gray-600 dark:text-zinc-300",
+    textColor: "text-gray-600 dark:text-zinc-300",
+    Icon: InfoIcon,
+  },
+  tip: {
+    border: "border-green-500 dark:border-green-800",
+    bg: "bg-green-200/25 dark:bg-green-950/70",
+    iconColor: "text-green-600 dark:text-green-200",
+    titleColor: "text-green-700 dark:text-green-200",
+    textColor: "text-green-600 dark:text-green-50",
+    Icon: LightbulbIcon,
+  },
+  info: {
+    border: "border-blue-400 dark:border-blue-900/60",
+    bg: "bg-blue-50 dark:bg-blue-950/40",
+    iconColor: "text-blue-400 dark:text-blue-200",
+    titleColor: "text-blue-700 dark:text-blue-200",
+    textColor: "text-blue-600 dark:text-blue-100",
+    Icon: InfoIcon,
+  },
+  caution: {
+    border: "border-yellow-400 dark:border-yellow-400/25",
+    bg: "bg-yellow-100/60 dark:bg-yellow-400/10",
+    iconColor: "text-yellow-500 dark:text-yellow-300",
+    titleColor: "text-yellow-600 dark:text-yellow-300",
+    textColor: "text-yellow-700 dark:text-yellow-200",
+    Icon: AlertTriangleIcon,
+  },
+  danger: {
+    border: "border-rose-400 dark:border-rose-800",
+    bg: "bg-rose-50 dark:bg-rose-950/40",
+    iconColor: "text-rose-400 dark:text-rose-300",
+    titleColor: "text-rose-800 dark:text-rose-300",
+    textColor: "text-rose-700 dark:text-rose-100",
+    Icon: ShieldAlertIcon,
+  },
+};
+
+type CalloutProps = {
+  type: keyof typeof stylesMap;
+  title?: string;
+  children: ReactNode;
+  className?: string;
+};
+
+export const Callout = ({ type, children, title, className }: CalloutProps) => {
+  const { border, bg, iconColor, titleColor, textColor, Icon } =
+    stylesMap[type];
+
+  return (
+    <div
+      className={cn(
+        "not-prose grid grid-cols-[fit-content_1fr] grid-rows-[fit-content_1fr] gap-x-4 gap-y-2 text-md rounded-md border p-4",
+        "[&_a]:underline [&_a]:decoration-current [&_a]:decoration-from-font [&_a]:underline-offset-4 hover:[&_a]:decoration-1",
+        "[&_code]:!bg-transparent [&_code]:!border-none",
+        title && "items-center",
+        border,
+        bg,
+        className,
+      )}
+    >
+      <Icon
+        className={cn(!title && "mt-1 translate-y-px", iconColor)}
+        size={20}
+        aria-hidden="true"
+      />
+      {title && <h3 className={cn("font-medium", titleColor)}>{title}</h3>}
+      <div className={cn("col-start-2", !title && "row-start-1", textColor)}>
+        {children}
+      </div>
+    </div>
+  );
+};

package/src/lib/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 border-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/lib/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/lib/ui/Tabs.tsx

@@ -0,0 +1,52 @@
+import * as React from "react";
+import * as TabsPrimitive from "@radix-ui/react-tabs";
+import { cn } from "../util/cn.js";
+
+const Tabs = TabsPrimitive.Root;
+
+const TabsList = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.List
+    ref={ref}
+    className={cn(
+      "inline-flex h-9 items-center justify-center rounded-lg bg-muted p-1 text-muted-foreground",
+      className,
+    )}
+    {...props}
+  />
+));
+TabsList.displayName = TabsPrimitive.List.displayName;
+
+const TabsTrigger = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Trigger
+    ref={ref}
+    className={cn(
+      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow",
+      className,
+    )}
+    {...props}
+  />
+));
+TabsTrigger.displayName = TabsPrimitive.Trigger.displayName;
+
+const TabsContent = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Content
+    ref={ref}
+    className={cn(
+      "mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+      className,
+    )}
+    {...props}
+  />
+));
+TabsContent.displayName = TabsPrimitive.Content.displayName;
+
+export { Tabs, TabsList, TabsTrigger, TabsContent };

package/src/lib/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/lib/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/lib/util/createVariantComponent.tsx

@@ -0,0 +1,30 @@
+import { cva } from "class-variance-authority";
+import { ClassValue } from "clsx";
+import * as React from "react";
+import { JSX } from "react/jsx-runtime";
+import { cn } from "./cn.js";
+
+const createVariantComponent = <
+  E extends keyof React.ReactHTML,
+  C extends ReturnType<typeof cva>,
+>(
+  tag: E,
+  cvx: ClassValue | C,
+  // variantProps: Array<keyof VariantProps<C>> = [],
+) => {
+  const MyVariant = ({
+    className,
+    ...props
+  }: JSX.IntrinsicElements[E] & { className?: ClassValue }) =>
+    React.createElement(tag, {
+      ...props,
+      className:
+        typeof cvx === "function" ? cvx({ className }) : cn(cvx, className),
+    });
+
+  MyVariant.displayName = `VariantComponent(${tag})`;
+
+  return MyVariant;
+};
+
+export default createVariantComponent;

package/src/lib/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/lib/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/lib/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/lib/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/lib/util/slugify.ts

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

package/src/lib/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/lib/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/lib/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]);
+};