@xyd-js/atlas 0.0.0-build

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

@@ -0,0 +1,69 @@
+import React, { useState, useMemo } from "react";
+import { UXNode } from "openux-js";
+
+import { 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 * as cn from "./ApiRefSamples.styles";
+
+export interface ApiRefSamplesProps {
+    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>
+            })
+        }
+    </atlas-apiref-samples>
+}

package/src/components/ApiRef/ApiRefSamples/index.ts

@@ -0,0 +1,7 @@
+export {
+    ApiRefSamples
+} from "./ApiRefSamples"
+
+export type {
+    ApiRefSamplesProps
+} from "./ApiRefSamples"

package/src/components/ApiRef/index.ts

@@ -0,0 +1,5 @@
+export * from "./ApiRefItem";
+
+export * from "./ApiRefProperties";
+
+export * from "./ApiRefSamples";

package/src/components/Atlas/Atlas.styles.tsx

@@ -0,0 +1,5 @@
+import {css} from "@linaria/core";
+
+export const AtlasHost = css`
+    width: 100%;
+`;

package/src/components/Atlas/Atlas.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+
+import { MDXCommonAtlasProps } from "./types";
+import { AtlasDecorator } from "./AtlasDecorator";
+import { AtlasPrimary } from "./AtlasPrimary";
+import { AtlasSecondary } from "./AtlasSecondary";
+
+import * as cn from "./Atlas.styles";
+
+interface AtlasProps<T> extends MDXCommonAtlasProps<T> {
+    kind: "secondary" | "primary" | undefined | null
+}
+
+export function Atlas<T>(props: AtlasProps<T>) {
+    let AtlasComponent: React.FC<MDXCommonAtlasProps<T>>;
+
+    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)
+            }
+        }
+    }
+
+    return <AtlasDecorator>
+        <div className={cn.AtlasHost}>
+            <AtlasComponent
+                references={references}
+                apiRefItemKind={props.apiRefItemKind}
+            />
+        </div>
+    </AtlasDecorator>
+}

package/src/components/Atlas/AtlasContext.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext } from "react";
+
+import { type Theme } from "@code-hike/lighter";
+
+export interface VariantToggleConfig {
+    key: string;
+    defaultValue: string;
+}
+
+export const AtlasContext = createContext<{
+    syntaxHighlight: Theme | null,
+    baseMatch?: string,
+    variantToggles?: VariantToggleConfig[], // Array of toggle configurations
+    Link?: any
+}>({
+    syntaxHighlight: null
+})
+
+export function useSyntaxHighlight() {
+    const context = useContext(AtlasContext)
+
+    if (!context) {
+        throw new Error("useSyntaxHighlight must be used within a AtlasContext")
+    }
+
+    return context.syntaxHighlight
+}
+
+export function useBaseMatch() {
+    const context = useContext(AtlasContext)
+
+    if (!context) {
+        throw new Error("useBaseMatch must be used within a AtlasContext")
+    }
+
+    return context.baseMatch
+}
+
+export function useVariantToggles() {
+    const context = useContext(AtlasContext)
+
+    if (!context) {
+        throw new Error("useVariantToggles must be used within a AtlasContext")
+    }
+
+    return context.variantToggles || []
+}

package/src/components/Atlas/AtlasDecorator.styles.ts

@@ -0,0 +1,22 @@
+import { css } from "@linaria/core";
+
+export default {
+    AtlasDecoratorHost: css`
+        @layer templates {
+           atlas-apiref-proptype {
+                font-size: var(--xyd-font-size-xsmall);
+                line-height: var(--xyd-line-height-xsmall);
+           }
+
+           atlas-apiref-item-showcase {
+            font-size: var(--xyd-font-size-small);
+            line-height: var(--xyd-line-height-medium);
+
+            p {
+                font-size: var(--xyd-font-size-small);
+                line-height: var(--xyd-line-height-medium);
+            }
+           }
+        }
+    `
+}

package/src/components/Atlas/AtlasDecorator.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+
+import cn from "./AtlasDecorator.styles";
+
+interface AtlasDecoratorProps {
+    children: React.ReactNode
+}
+
+export function AtlasDecorator({ children }: AtlasDecoratorProps) {
+    return <atlas-decorator
+        className={cn.AtlasDecoratorHost}
+    >
+        {children}
+    </atlas-decorator>
+}

package/src/components/Atlas/AtlasLazy/AtlasLazy.styles.tsx

@@ -0,0 +1,9 @@
+import {css} from "@linaria/core";
+
+export const AtlasLazyItemHost = css`
+    padding: 16px 0;
+`;
+
+export const AtlasLazyItemFirst = css`
+    padding: 4px 0;
+`;

package/src/components/Atlas/AtlasLazy/AtlasLazy.tsx

@@ -0,0 +1,42 @@
+import React, {useEffect, useRef} from "react";
+
+import {Reference} from "@xyd-js/uniform";
+
+import {ApiRefItem} from "@/components/ApiRef";
+
+import * as cn from "./AtlasLazy.styles";
+
+export interface AtlasLazyProps {
+    references: Reference[]
+    urlPrefix: string
+    slug: string,
+    onLoaded?: () => void
+}
+
+export function AtlasLazy(props: AtlasLazyProps) {
+    return props.references?.map((reference: any, i: number) => <>
+        <div
+            key={i}
+            // TODO: slug should be passed from reference or somrthing
+            // ref={`api-reference/${reference.title}` === slug ? targetRef : null} // Attach ref to the 30th item
+            className={`${cn.AtlasLazyItemHost} ${i === 0 && cn.AtlasLazyItemFirst}`}
+            // TODO: slug prefix props
+            data-slug={`${props.urlPrefix}/${reference.canonical?.title}`}
+        >
+            <ItemWrapper
+                reference={reference}
+                onLoad={i === props.references.length - 1 ? props.onLoaded : null}
+            />
+        </div>
+    </>)
+}
+
+function ItemWrapper({reference, onLoad}) {
+    useEffect(() => {
+        onLoad && onLoad()
+    }, []);
+
+    return <>
+        <ApiRefItem reference={reference}/>
+    </>
+}

package/src/components/Atlas/AtlasLazy/hooks.ts

@@ -0,0 +1,29 @@
+import {useEffect} from "react";
+
+function getScrollPosition() {
+    return sessionStorage.getItem('scrollPosition');
+}
+
+export function useScrollRestoration() {
+    useEffect(() => {
+        const saveScrollPosition = () => {
+            sessionStorage.setItem('scrollPosition', window.scrollY.toString());
+        };
+
+        window.addEventListener('beforeunload', saveScrollPosition);
+
+        return () => {
+            window.removeEventListener('beforeunload', saveScrollPosition);
+        };
+    }, []);
+
+    return [
+        () => getScrollPosition(),
+        () => {
+            const scrollPosition = getScrollPosition();
+            if (scrollPosition) {
+                window.scrollTo(0, parseInt(scrollPosition, 10));
+            }
+        }
+    ]
+}

package/src/components/Atlas/AtlasLazy/index.ts

@@ -0,0 +1,7 @@
+export {
+    AtlasLazy,
+} from "./AtlasLazy";
+
+export type {
+    AtlasLazyProps
+} from "./AtlasLazy";

package/src/components/Atlas/AtlasPrimary.tsx

@@ -0,0 +1,21 @@
+import React, {} from "react";
+
+import {ApiRefItem} from "@/components/ApiRef";
+
+import {MDXCommonAtlasProps} from "./types";
+
+export function AtlasPrimary<T>(props: MDXCommonAtlasProps<T>) {
+    return <>
+        {
+            props.references?.map((reference, i) =>
+                <ApiRefItem
+                    key={i}
+                    reference={{
+                        ...reference
+                    }}
+                    kind={props.apiRefItemKind || undefined}
+                />
+            )
+        }
+    </>
+}

package/src/components/Atlas/AtlasSecondary.tsx

@@ -0,0 +1,148 @@
+import * as React from "react"
+
+import {type Theme} from "@code-hike/lighter";
+
+import {
+    Heading,
+    Table,
+    Details,
+    Code,
+} from "@xyd-js/components/writer";
+import {CodeSample} from "@xyd-js/components/coder";
+
+import {MDXCommonAtlasProps} from "@/components/Atlas/types";
+import {useSyntaxHighlight} from "./AtlasContext";
+import {IconQuote} from "@/components/Icon";
+
+// TODO: interface should be imported from somewhere
+interface CodeSourceContext {
+    fileName: string;
+    fileFullPath: string;
+    sourcecode: string;
+}
+
+const MAX_REFERENCES = 2;
+
+interface ReferenceItemProps {
+    reference: any;
+    index: number;
+    syntaxHighlight: Theme | null;
+}
+
+
+export function AtlasSecondary<T>({references}: MDXCommonAtlasProps<T>) {
+    const syntaxHighlight = useSyntaxHighlight()
+
+    if (!references) return null;
+
+    const initialReferences = references.slice(0, MAX_REFERENCES);
+    const remainingReferences = references.slice(MAX_REFERENCES);
+
+    const showMoreText = remainingReferences.length > 0 ?
+        `Show more (${remainingReferences.length}) reference${remainingReferences.length === 1 ? '' : 's'}` :
+        '';
+
+    return (
+        <>
+            {initialReferences.map((reference, i) => (
+                <$ReferenceItem
+                    key={i}
+                    reference={reference}
+                    index={i}
+                    syntaxHighlight={syntaxHighlight}
+                />
+            ))}
+
+            {remainingReferences.length > 0 && (
+                <Details
+                    label={showMoreText}
+                >
+                    {remainingReferences.map((reference, i) => (
+                        <$ReferenceItem
+                            key={i + MAX_REFERENCES}
+                            reference={reference}
+                            index={i + MAX_REFERENCES}
+                            syntaxHighlight={syntaxHighlight}
+                        />
+                    ))}
+                </Details>
+            )}
+        </>
+    )
+}
+
+function $ReferenceItem({reference, index, syntaxHighlight}: ReferenceItemProps) {
+    return (
+        <React.Fragment key={index}>
+            <Heading size={3}>
+                {reference.title}
+            </Heading>
+
+            {/*<p>*/}
+            {/*    {uniformChild(reference.description)}*/}
+            {/*</p>*/}
+
+            {
+                reference.context?.fileName && <Details
+                    label=""
+                    kind="tertiary"
+                    title={<>
+                        Source code in <Code>{reference.context.fileFullPath}</Code>
+                    </>}
+                    icon={<IconQuote/>}>
+                    <CodeSample
+                        name={reference.context.fileName}
+                        description={reference.context.sourcecode.description}
+                        theme={syntaxHighlight || undefined}
+                        codeblocks={[
+                            {
+                                lang: reference.context.sourcecode.lang,
+                                meta: "",
+                                value: reference.context.sourcecode.code
+                            }
+                        ]}
+                    />
+                    {/* {parseChild(reference.context.sourcecode)} */}
+                </Details>
+            }
+
+            {
+                reference.definitions.map((definition: any, index: number) => {
+                    return (
+                        <React.Fragment key={index}>
+                            <Heading size={4}>
+                                {definition.title}
+                            </Heading>
+                            <Table>
+                                <Table.Head>
+                                    <Table.Tr>
+                                        <Table.Th>Name</Table.Th>
+                                        <Table.Th>Type</Table.Th>
+                                        <Table.Th>Description</Table.Th>
+                                    </Table.Tr>
+                                </Table.Head>
+                                <Table.Body>
+                                    {definition.properties?.map((property: any, propIndex: number) => (
+                                        <Table.Tr key={propIndex}>
+                                            <Table.Td>
+                                                <Code>{property.name}</Code>
+                                            </Table.Td>
+                                            <Table.Td>
+                                                <Code>{property.type}</Code>
+                                            </Table.Td>
+                                            <Table.Td muted>
+                                                {property.description}
+                                            </Table.Td>
+                                        </Table.Tr>
+                                    ))}
+                                </Table.Body>
+                            </Table>
+                        </React.Fragment>
+                    )
+                })
+            }
+
+            <br/>
+        </React.Fragment>
+    )
+}

package/src/components/Atlas/index.ts

@@ -0,0 +1,7 @@
+export { AtlasLazy } from "./AtlasLazy"
+
+export { Atlas } from "./Atlas"
+
+export { AtlasContext, type VariantToggleConfig } from "./AtlasContext"
+
+export type { AtlasProps } from "./types"

package/src/components/Atlas/types.ts

@@ -0,0 +1,11 @@
+import type { Reference } from "@xyd-js/uniform";
+
+// TODO unify MDXCommonAtlasProps and AtlasProps
+export interface MDXCommonAtlasProps<T> {
+    references: Reference<T>[] | []
+    apiRefItemKind?: "secondary"
+}
+
+export interface AtlasProps {
+    references: Reference<any>[]
+}

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

@@ -0,0 +1,58 @@
+import {css} from "@linaria/core";
+
+export const CodeSampleButtonsHost = css`
+    position: relative;
+    max-width: 100%;
+`;
+
+export const CodeSampleButtonsContainer = css`
+    display: inline-flex;
+    width: 100%;
+    align-items: center;
+    border-radius: 8px;
+    background-color: var(--XydAtlas-Component-Code-SampleButtons__color-containerBackground);
+`;
+
+export const CodeSampleButtonsArrowHost = css`
+    padding: 8px;
+    background-color: var(--white, #ffffff);
+    box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+`;
+
+export const CodeSampleButtonsArrowIcon = css`
+    width: 16px;
+    height: 16px;
+`;
+
+export const CodeSampleButtonsScrollerHost = css`
+    overflow-x: auto;
+    flex-grow: 1;
+    font-weight: var(--xyd-font-weight-semibold);
+`;
+
+export const CodeSampleButtonsScrollerContainer = css`
+    display: inline-flex;
+    gap: 4px;
+    padding: 4px;
+    margin-left: 4px;
+`;
+
+export const CodeSampleButtonsButtonHost = css`
+    padding: 4px 16px;
+    border-radius: 0.375rem;
+    white-space: nowrap;
+    transition-property: color, background-color, border-color, text-decoration-color, fill, stroke;
+    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+    transition-duration: 300ms;
+    color: var(--XydAtlas-Component-Code-SampleButtons__color);
+    
+    &:hover {
+        color: var(--XydAtlas-Component-Code-SampleButtons__color--active);
+    }
+`;
+
+export const CodeSampleButtonsButtonActive = css`
+    color: var(--XydAtlas-Component-Code-SampleButtons__color--active);
+    background-color: var(--XydAtlas-Component-Code-SampleButtons__color-background--active);
+    box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+`;

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

@@ -0,0 +1,97 @@
+import React, {useState, useRef, useEffect} from 'react'
+import {ChevronLeft, ChevronRight} from "lucide-react"
+
+import {Example} from "@xyd-js/uniform";
+
+import * as cn from "./CodeSampleButtons.styles";
+
+export interface CodeExampleButtonsProps {
+    examples: Example[]
+    activeExample: Example | null
+    onClick: (example: Example) => void
+}
+
+export function CodeExampleButtons({examples, activeExample, onClick}: CodeExampleButtonsProps) {
+    const [showLeftArrow, setShowLeftArrow] = useState(false)
+    const [showRightArrow, setShowRightArrow] = useState(false)
+    const scrollContainerRef = useRef<HTMLDivElement>(null)
+
+    const handleScroll = () => {
+        if (scrollContainerRef.current) {
+            const {scrollLeft, scrollWidth, clientWidth} = scrollContainerRef.current
+            setShowLeftArrow(scrollLeft > 0)
+            setShowRightArrow(scrollLeft < scrollWidth - clientWidth)
+        }
+    }
+
+    useEffect(() => {
+        handleScroll()
+        window.addEventListener('resize', handleScroll)
+        return () => window.removeEventListener('resize', handleScroll)
+    }, [])
+
+    const scroll = (direction: 'left' | 'right') => {
+        if (scrollContainerRef.current) {
+            const scrollAmount = direction === 'left' ? -200 : 200
+            scrollContainerRef.current.scrollBy({left: scrollAmount, behavior: 'smooth'})
+        }
+    }
+
+    return (
+        <div className={cn.CodeSampleButtonsHost}>
+            <div className={cn.CodeSampleButtonsContainer}>
+                {showLeftArrow && (
+                    <button
+                        onClick={() => scroll('left')}
+                        className={cn.CodeSampleButtonsArrowHost}
+                    >
+                        <ChevronLeft className={cn.CodeSampleButtonsArrowIcon}/>
+                    </button>
+                )}
+                <div
+                    ref={scrollContainerRef}
+                    onScroll={handleScroll}
+                    className={cn.CodeSampleButtonsScrollerHost}
+                >
+                    <div className={cn.CodeSampleButtonsScrollerContainer}>
+                        {examples?.map((example) => (
+                            <SampleButton
+                                key={example.codeblock.title}
+                                onClick={() => onClick(example)}
+                                example={example}
+                                activeExample={activeExample}
+                            >
+                                {(example.codeblock.title || null)}
+                            </SampleButton>
+                        ))}
+                    </div>
+                </div>
+                {showRightArrow && (
+                    <button
+                        onClick={() => scroll('right')}
+                        className={cn.CodeSampleButtonsArrowHost}
+                    >
+                        <ChevronRight className={cn.CodeSampleButtonsArrowIcon}/>
+                    </button>
+                )}
+            </div>
+        </div>
+    )
+}
+
+function SampleButton({onClick, children, activeExample, example}: {
+    onClick: () => void,
+    children: React.ReactNode,
+    example: Example,
+    activeExample: Example | null,
+}) {
+    const markExampleAsActive = (activeExample?.description && activeExample?.description === example?.description) ||
+        (activeExample?.codeblock?.title && activeExample?.codeblock?.title === example.codeblock.title)
+
+    return <button
+        onClick={onClick}
+        className={`${cn.CodeSampleButtonsButtonHost} ${markExampleAsActive && cn.CodeSampleButtonsButtonActive}`}
+    >
+        {children}
+    </button>
+}

package/src/components/Code/CodeSampleButtons/index.ts

@@ -0,0 +1,7 @@
+export {
+    CodeExampleButtons,
+} from "./CodeSampleButtons"
+
+export type {
+    CodeExampleButtonsProps
+} from "./CodeSampleButtons"

package/src/components/Code/index.ts

@@ -0,0 +1,2 @@
+export * from "./CodeSampleButtons";
+