Add anchors to fields

Author: xPaw

src/components/Docs/SchemaClass.tsx

@@ -1,4 +1,4 @@
-import React, { useContext, useMemo, useState } from "react";
+import React, { useContext, useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { styled } from "@linaria/react";
 import * as api from "./api";
@@ -14,10 +14,12 @@ import {
   useSearchWords,
   useSearchOffsets,
   useSearchMetadata,
+  useFieldParam,
 } from "./utils/filtering";
 import { formatHexOffset } from "./utils/format";
 import { computeBitfieldInfo, type BitfieldInfo } from "./utils/bitfields";
 import {
+  AnchorName,
   CollapsedItemsLink,
   CommonGroupMembers,
   CommonGroupSignature,
@@ -50,6 +52,11 @@ const FieldRow = styled.div`
   &[data-highlighted] {
     background-color: var(--search-highlight);
   }
+
+  &[data-anchored] {
+    background-color: var(--search-highlight);
+    border-color: var(--highlight);
+  }
 `;
 
 const FieldIcon = styled.div`
@@ -147,6 +154,7 @@ export const SchemaClassView: React.FC<{
   const searchWords = useSearchWords();
   const searchOffsets = useSearchOffsets();
   const searchMetadata = useSearchMetadata();
+  const fieldParam = useFieldParam();
 
   const isSearching = searchWords.length > 0 || searchOffsets.size > 0 || searchMetadata.length > 0;
 
@@ -213,13 +221,15 @@ export const SchemaClassView: React.FC<{
             <SchemaFieldView
               key={`${field.name}-${field.offset}`}
               field={field}
+              fieldUrlBase={`${root}/${declaration.module}/${declaration.name}`}
               bitfield={bitfieldInfo.get(field)}
               highlighted={
                 collapseNonMatching ||
                 (searchWords.length > 0 && matchesWords(field.name, searchWords)) ||
                 (searchOffsets.size > 0 && searchOffsets.has(field.offset)) ||
                 (searchMetadata.length > 0 && matchesMetadataKeys(field.metadata, searchMetadata))
               }
+              anchored={fieldParam === field.name}
             />
           ))}
           {hiddenCount > 0 && (
@@ -365,25 +375,52 @@ const BitfieldPadding = styled.div`
 
 function SchemaFieldView({
   field,
+  fieldUrlBase,
   bitfield,
   highlighted,
+  anchored,
 }: {
   field: api.SchemaField;
+  fieldUrlBase: string;
   bitfield?: BitfieldInfo;
   highlighted: boolean;
+  anchored: boolean;
 }) {
   const { root } = useContext(DeclarationsContext);
   const navigate = useNavigate();
   const offsetHex = formatHexOffset(field.offset);
+  const rowRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (anchored && rowRef.current) {
+      rowRef.current.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+  }, [anchored]);
+
+  const copyAnchorLink = (e: React.MouseEvent) => {
+    e.preventDefault();
+    const fieldUrl = `${fieldUrlBase}?field=${encodeURIComponent(field.name)}`;
+    const fullUrl = `${window.location.origin}${window.location.pathname}#${fieldUrl}`;
+    navigator.clipboard.writeText(fullUrl);
+    navigate(fieldUrl, { replace: true });
+  };
+
   return (
     <>
-      <FieldRow data-highlighted={highlighted || undefined}>
+      <FieldRow
+        ref={rowRef}
+        data-highlighted={highlighted || undefined}
+        data-anchored={anchored || undefined}
+      >
         <FieldIcon>
           <KindIcon kind="field" size="small" />
         </FieldIcon>
         <FieldContent>
           <FieldSignature>
-            {field.name}: <SchemaTypeView type={field.type} />
+            <AnchorName onClick={copyAnchorLink} title="Copy link to field">
+              {field.name}
+            </AnchorName>
+            : <SchemaTypeView type={field.type} />
             {bitfield && (
               <BitRange>
                 bit{bitfield.bitCount !== 1 ? "s" : ""} {bitfield.bitOffset}

src/components/Docs/SchemaEnum.tsx

@@ -1,5 +1,6 @@
 import * as api from "./api";
-import React, { useContext, useMemo } from "react";
+import React, { useContext, useEffect, useMemo, useRef } from "react";
+import { useNavigate } from "react-router-dom";
 import { styled } from "@linaria/react";
 import { ColoredSyntax } from "../ColoredSyntax";
 import { KindIcon } from "../KindIcon";
@@ -14,8 +15,10 @@ import {
   matchesMetadataKeys,
   useSearchWords,
   useSearchMetadata,
+  useFieldParam,
 } from "./utils/filtering";
 import {
+  AnchorName,
   CollapsedItemsLink,
   CommonGroupMembers,
   CommonGroupSignature,
@@ -48,6 +51,10 @@ const EnumMemberWrapper = styled.div`
   &[data-highlighted] {
     background-color: var(--search-highlight);
   }
+
+  &[data-anchored] {
+    background-color: var(--search-highlight);
+  }
 `;
 
 const EnumMemberIcon = styled.div`
@@ -85,6 +92,7 @@ export const SchemaEnumView: React.FC<{
   const { root } = useContext(DeclarationsContext);
   const searchWords = useSearchWords();
   const searchMetadata = useSearchMetadata();
+  const fieldParam = useFieldParam();
 
   const isSearching = searchWords.length > 0 || searchMetadata.length > 0;
   const nameMatches = searchWords.length > 0 && matchesWords(declaration.name, searchWords);
@@ -126,11 +134,13 @@ export const SchemaEnumView: React.FC<{
             <EnumMemberView
               key={`${member.name}-${member.value}`}
               member={member}
+              fieldUrlBase={`${root}/${declaration.module}/${declaration.name}`}
               highlighted={
                 collapseNonMatching ||
                 (searchWords.length > 0 && matchesWords(member.name, searchWords)) ||
                 (searchMetadata.length > 0 && matchesMetadataKeys(member.metadata, searchMetadata))
               }
+              anchored={fieldParam === member.name}
             />
           ))}
           {hiddenCount > 0 && (
@@ -148,21 +158,47 @@ export const SchemaEnumView: React.FC<{
 
 function EnumMemberView({
   member,
+  fieldUrlBase,
   highlighted,
+  anchored,
 }: {
   member: api.SchemaEnumMember;
+  fieldUrlBase: string;
   highlighted: boolean;
+  anchored: boolean;
 }) {
+  const rowRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (anchored && rowRef.current) {
+      rowRef.current.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+  }, [anchored]);
+
+  const navigate = useNavigate();
+  const copyAnchorLink = (e: React.MouseEvent) => {
+    e.preventDefault();
+    const fieldUrl = `${fieldUrlBase}?field=${encodeURIComponent(member.name)}`;
+    const fullUrl = `${window.location.origin}${window.location.pathname}#${fieldUrl}`;
+    navigator.clipboard.writeText(fullUrl);
+    navigate(fieldUrl, { replace: true });
+  };
+
   return (
-    <EnumMemberWrapper data-highlighted={highlighted || undefined}>
+    <EnumMemberWrapper
+      ref={rowRef}
+      data-highlighted={highlighted || undefined}
+      data-anchored={anchored || undefined}
+    >
       <EnumMemberIcon>
         <KindIcon kind="enum-member" size="small" />
       </EnumMemberIcon>
       <EnumMemberContent>
         <EnumMemberSignature>
-          <span>
-            {member.name} = <ColoredSyntax kind="literal">{member.value}</ColoredSyntax>
-          </span>
+          <AnchorName onClick={copyAnchorLink} title="Copy link to member">
+            {member.name}
+          </AnchorName>{" "}
+          = <ColoredSyntax kind="literal">{member.value}</ColoredSyntax>
           <EnumMemberHex>{formatHexOffset(member.value)}</EnumMemberHex>
         </EnumMemberSignature>
         {member.metadata && <MetadataTags metadata={member.metadata} />}

src/components/Docs/utils/filtering.tsx

@@ -1,5 +1,5 @@
 import { useContext, useMemo } from "react";
-import { useParams } from "react-router-dom";
+import { useLocation, useParams } from "react-router-dom";
 import { SearchContext } from "../../Search/SearchContext";
 import * as api from "../api";
 
@@ -58,6 +58,11 @@ export function useSearchOffsets(): Set<number> {
   }, [search]);
 }
 
+export function useFieldParam(): string | null {
+  const location = useLocation();
+  return useMemo(() => new URLSearchParams(location.search).get("field"), [location.search]);
+}
+
 export function useSearchMetadata(): string[] {
   const { search } = useContext(SearchContext);
   return useMemo(

src/components/Docs/utils/styles.tsx

@@ -105,6 +105,15 @@ export const SectionToggle = styled.button`
   }
 `;
 
+export const AnchorName = styled.span`
+  cursor: pointer;
+
+  &:hover {
+    text-decoration: underline;
+    text-decoration-color: var(--text-dim);
+  }
+`;
+
 export const CollapsedItemsLink = styled(Link)`
   display: block;
   padding: 4px 8px;