@xyd-js/atlas 0.0.0-build-099b7bb-20250918135344 → 0.0.0-build-9f87f13-20250930210637

package/src/components/ApiRef/ApiRefSamples/ApiRefSamples.tsx

@@ -1,69 +1,125 @@
-import React, { useState, useMemo } from "react";
+import React, { useState, useMemo, useContext } from "react";
 import { UXNode } from "openux-js";
 
-import { ExampleRoot } from "@xyd-js/uniform";
+import { Example, ExampleRoot } from "@xyd-js/uniform";
 import { CodeSample, type CodeThemeBlockProps } from "@xyd-js/components/coder";
 
 import { CodeExampleButtons } from "@/components/Code";
-import { useSyntaxHighlight } from "@/components/Atlas/AtlasContext";
+import {
+  AtlasContext,
+  useSyntaxHighlight,
+} from "@/components/Atlas/AtlasContext";
 
 import * as cn from "./ApiRefSamples.styles";
 
 export interface ApiRefSamplesProps {
-    examples: ExampleRoot
+  examples: ExampleRoot;
 }
 
 export function ApiRefSamples({ examples }: ApiRefSamplesProps) {
-    const syntaxHighlight = useSyntaxHighlight()
-    const [activeExampleIndices, setActiveExampleIndices] = useState<Record<number, number>>({})
-
-    const handleExampleChange = (groupIndex: number, exampleIndex: number) => {
-        setActiveExampleIndices(prev => ({
-            ...prev,
-            [groupIndex]: exampleIndex
-        }))
-    }
-
-    return <atlas-apiref-samples className={cn.ApiRefSamplesContainerHost}>
-        {
-            examples.groups?.map(({ description, examples: example }, i) => {
-                const activeExampleIndex = activeExampleIndices[i] || 0
-                const activeExample = example[activeExampleIndex]
-
-                const codeblocks = activeExample?.codeblock?.tabs?.map(tab => ({
-                    value: String(tab.code || ""),
-                    lang: String(tab.language || ""),
-                    meta: String(tab.context || ""),
-                    highlighted: tab.highlighted
-                } as CodeThemeBlockProps)) || []
-
-                return <UXNode
-                    name="APIRefSample"
-                    props={activeExample}
-                >
-                    <div key={i} className={cn.ApiRefSamplesGroupHost}>
-                        {
-                            example?.length > 1
-                                ? <CodeExampleButtons
-                                    activeExample={activeExample}
-                                    examples={example}
-                                    onClick={(ex) => {
-                                        const index = example.findIndex(e => e === ex)
-                                        handleExampleChange(i, index)
-                                    }}
-                                />
-                                : null
-                        }
-                        <CodeSample
-                            name={String(i)}
-                            description={description || ""}
-                            codeblocks={codeblocks}
-                            theme={syntaxHighlight || undefined}
-                        // controlByMeta
-                        />
-                    </div>
-                </UXNode>
-            })
-        }
+  const [activeExampleIndices, setActiveExampleIndices] = useState<
+    Record<number, number>
+  >({});
+
+  const handleExampleChange = (groupIndex: number, exampleIndex: number) => {
+    setActiveExampleIndices((prev) => ({
+      ...prev,
+      [groupIndex]: exampleIndex,
+    }));
+  };
+
+  return (
+    <atlas-apiref-samples className={cn.ApiRefSamplesContainerHost}>
+      {examples.groups?.map(({ description, examples: samples }, i) => {
+        const activeExampleIndex = activeExampleIndices[i] || 0;
+        const activeExample = samples[activeExampleIndex];
+
+        return (
+          <CodeSampleItem
+            key={i}
+            currentExample={activeExample}
+            examples={samples}
+            name={String(i)}
+            description={description}
+            onExampleChange={(ex) => {
+              const index = samples.findIndex((e) => e === ex);
+              handleExampleChange(i, index);
+            }}
+          />
+        );
+      })}
     </atlas-apiref-samples>
-}
+  );
+}
+
+interface CodeSampleItemProps {
+  currentExample: Example;
+  examples: Example[];
+  name: string;
+  description?: string;
+  onExampleChange: (example: Example) => void;
+}
+
+function CodeSampleItem(props: CodeSampleItemProps) {
+  const { currentExample, examples, name, description, onExampleChange } =
+    props;
+  const { markdownFormat } = useContext(AtlasContext);
+  const syntaxHighlight = useSyntaxHighlight();
+
+  const shouldRenderAllExamples = markdownFormat;
+
+  // example tabs
+  const buttons = examples?.length > 1 && (
+    <CodeExampleButtons
+      activeExample={currentExample}
+      examples={examples}
+      onClick={onExampleChange}
+    />
+  );
+
+  const singleCodeSample = (
+    <UXNode name="APIRefSample" props={currentExample}>
+      <CodeSample
+        name={name}
+        description={description || ""}
+        codeblocks={createCodeblocks(currentExample)}
+        theme={syntaxHighlight || undefined}
+        markdownFormat={markdownFormat}
+      />
+    </UXNode>
+  );
+
+  const allCodeSamples = examples.map((example, index) => (
+    <UXNode key={index} name="APIRefSample" props={example}>
+      <CodeSample
+        name={`${name}-${example.codeblock?.title || index}`}
+        description={example.codeblock?.title || description || ""}
+        codeblocks={createCodeblocks(example)}
+        theme={syntaxHighlight || undefined}
+        markdownFormat={markdownFormat}
+      />
+    </UXNode>
+  ));
+
+  return (
+    <div key={name} className={cn.ApiRefSamplesGroupHost}>
+      {buttons}
+      {shouldRenderAllExamples ? allCodeSamples : singleCodeSample}
+    </div>
+  );
+}
+
+// Helper function to create codeblocks from an example
+function createCodeblocks(example: Example): CodeThemeBlockProps[] {
+  return (
+    example?.codeblock?.tabs?.map(
+      (tab) =>
+        ({
+          value: String(tab.code || ""),
+          lang: String(tab.language || ""),
+          meta: String(tab.context || ""),
+          highlighted: tab.highlighted,
+        }) as CodeThemeBlockProps
+    ) || []
+  );
+}

package/src/components/Atlas/Atlas.tsx

@@ -6,38 +6,52 @@ import { AtlasPrimary } from "./AtlasPrimary";
 import { AtlasSecondary } from "./AtlasSecondary";
 
 import * as cn from "./Atlas.styles";
+import { UXAnalytics } from "openux-js";
 
 interface AtlasProps<T> extends MDXCommonAtlasProps<T> {
-    kind: "secondary" | "primary" | undefined | null
+  kind: "secondary" | "primary" | undefined | null;
+  analytics?: boolean;
 }
 
+const noopAnalytics = {
+  track: () => {},
+};
+
 export function Atlas<T>(props: AtlasProps<T>) {
-    let AtlasComponent: React.FC<MDXCommonAtlasProps<T>>;
+  let AtlasComponent: React.FC<MDXCommonAtlasProps<T>>;
 
-    if (props.kind === "secondary") {
-        AtlasComponent = AtlasSecondary;
-    } else {
-        AtlasComponent = AtlasPrimary;
-    }
+  if (props.kind === "secondary") {
+    AtlasComponent = AtlasSecondary;
+  } else {
+    AtlasComponent = AtlasPrimary;
+  }
 
-    let references = props.references
-    {
-        // TODO: find better solution - if we pass from md then its string
-        if (references && typeof references === "string") { // TODO: DO IT BETTER
-            try {
-                references = JSON.parse(references)
-            } catch (error) {
-                console.error("Error parsing references", error)
-            }
-        }
+  let references = props.references;
+  {
+    // TODO: find better solution - if we pass from md then its string
+    if (references && typeof references === "string") {
+      // TODO: DO IT BETTER
+      try {
+        references = JSON.parse(references);
+      } catch (error) {
+        console.error("Error parsing references", error);
+      }
     }
+  }
 
-    return <AtlasDecorator>
+  // TODO: temporary, remove when we will have proper analytics
+  const Wrapper = props.analytics ? UXAnalytics : React.Fragment;
+  
+  return (
+    <Wrapper analytics={noopAnalytics}>
+      <AtlasDecorator>
         <div className={cn.AtlasHost}>
-            <AtlasComponent
-                references={references}
-                apiRefItemKind={props.apiRefItemKind}
-            />
+          <AtlasComponent
+            references={references}
+            apiRefItemKind={props.apiRefItemKind}
+          />
         </div>
-    </AtlasDecorator>
-}
+      </AtlasDecorator>
+    </Wrapper>
+  );
+}

package/src/components/Atlas/AtlasContext.tsx

@@ -9,11 +9,13 @@ export interface VariantToggleConfig {
 
 export const AtlasContext = createContext<{
     syntaxHighlight: Theme | null,
+    markdownFormat?: boolean,
     baseMatch?: string,
     variantToggles?: VariantToggleConfig[], // Array of toggle configurations
     Link?: any
 }>({
-    syntaxHighlight: null
+    syntaxHighlight: null,
+    markdownFormat: false
 })
 
 export function useSyntaxHighlight() {

package/src/components/Code/CodeSampleButtons/CodeSampleButtons.tsx

@@ -38,7 +38,7 @@ export function CodeExampleButtons({examples, activeExample, onClick}: CodeExamp
     }
 
     return (
-        <div className={cn.CodeSampleButtonsHost}>
+        <atlas-sample-buttons className={cn.CodeSampleButtonsHost}>
             <div className={cn.CodeSampleButtonsContainer}>
                 {showLeftArrow && (
                     <button
@@ -75,7 +75,7 @@ export function CodeExampleButtons({examples, activeExample, onClick}: CodeExamp
                     </button>
                 )}
             </div>
-        </div>
+        </atlas-sample-buttons>
     )
 }
 
@@ -89,6 +89,7 @@ function SampleButton({onClick, children, activeExample, example}: {
         (activeExample?.codeblock?.title && activeExample?.codeblock?.title === example.codeblock.title)
 
     return <button
+        data-sample-button-title={example.codeblock.title}
         onClick={onClick}
         className={`${cn.CodeSampleButtonsButtonHost} ${markExampleAsActive && cn.CodeSampleButtonsButtonActive}`}
     >

package/types.d.ts

@@ -12,10 +12,14 @@ declare global {
         'atlas-apiref-definitions': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-properties': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-variant': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+        'atlas-apiref-prop': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-propname': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-proptype': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-propmeta': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
         'atlas-apiref-meta-info': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+        'atlas-apiref-propdescription': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+
+        'atlas-sample-buttons': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
       }
     }
   }