Improve docs UI and Mermaid rendering (#125)

Refactor documentation for clarity and organization. Upgrade the
@biomejs/biome dependency to version 2.4.9. Clean up imports and improve
component structure in the documentation pages.

## Summary by Sourcery

Refine documentation rendering and UI components while updating tooling
dependencies.

New Features:
- Improve Mermaid diagram rendering in docs with explicit SVG rendering
and stricter security configuration.

Bug Fixes:
- Use stable keys for mapped feature and FAQ items on the docs home page
to avoid React key issues.
- Adjust field error list keys to avoid collisions and improve React
reconciliation.

Enhancements:
- Clean up and reorder exports, imports, and hook dependencies across UI
components for consistency and maintainability.
- Streamline docs routing and loader types by removing unused parameters
and simplifying language handling.
- Improve user-facing error and status messages with template literals
and clearer formatting.

Build:
- Upgrade @biomejs/biome to version 2.4.9 and consolidate Biome
configuration by removing redundant docs-specific settings.

Documentation:
- Tidy documentation page composition and table-of-contents handling for
clearer structure.

1 files changed, 20 insertions, 7 deletions

diff --git a/packages/docs/app/components/mermaid.tsx b/packages/docs/app/components/mermaid.tsx
index 2df47cc..fe153ec 100644
--- a/packages/docs/app/components/mermaid.tsx
+++ b/packages/docs/app/components/mermaid.tsx
@@ -6,24 +6,37 @@ import { useEffect, useRef } from "react";
 mermaid.initialize({
   startOnLoad: false,
   theme: "default",
+  securityLevel: "strict",
 });
 
 export function Mermaid({ chart }: { chart: string }) {
   const ref = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
-    if (ref.current) {
-      mermaid.run({
-        nodes: [ref.current],
+    let current = true;
+    const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
+    mermaid
+      .render(id, chart)
+      .then(({ svg }) => {
+        if (!current) return;
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(svg, "image/svg+xml");
+        const svgEl = doc.querySelector("svg");
+        if (ref.current && svgEl) {
+          ref.current.replaceChildren(svgEl);
+        }
+      })
+      .catch(() => {
+        if (current) ref.current?.replaceChildren();
       });
-    }
+    return () => {
+      current = false;
+    };
   }, [chart]);
 
   return (
     <div className="not-prose my-6">
-      <div ref={ref} className="mermaid">
-        {chart}
-      </div>
+      <div ref={ref} className="mermaid" />
     </div>
   );
 }