@xyd-js/components 0.1.0-xyd.5 → 0.1.0-xyd.52

package/src/writer/Details/Details.tsx

@@ -1,74 +1,118 @@
 import React from "react"
 
-import {$details} from "./Details.styles";
+import * as cn from "./Details.styles";
 
-interface BaseDetailsProps {
+/**
+ * Base interface for all Details component variants
+ */
+export interface BaseDetailsProps {
+    /** Content to be displayed inside the details element */
     children: React.ReactNode;
+
+    /** Label text displayed in the summary */
     label: string;
+
+    /** Optional icon element to be displayed in the summary */
+    icon?: React.ReactElement;
+
+    /** Optional CSS class name for custom styling */
+    className?: string;
+}
+
+/**
+ * Props for the tertiary variant of the Details component
+ */
+export interface TertiaryDetailsProps extends BaseDetailsProps {
+    /** Specifies the tertiary variant */
+    kind: "tertiary";
+
+    /** Title text or element displayed in the summary */
+    title: string | React.ReactNode;
 }
 
-interface SecondaryDetailsProps extends BaseDetailsProps {
+/**
+ * Props for the secondary variant of the Details component
+ */
+export interface SecondaryDetailsProps extends BaseDetailsProps {
+    /** Specifies the secondary variant */
     kind: "secondary";
-    title: string;
+
+    /** Title text or element displayed in the summary */
+    title: string | React.ReactNode;
 }
 
-interface PrimaryDetailsProps extends BaseDetailsProps {
+/**
+ * Props for the primary variant of the Details component
+ */
+export interface PrimaryDetailsProps extends BaseDetailsProps {
+    /** Specifies the primary variant (default) */
     kind?: "primary";
 }
 
-export type DetailsProps = PrimaryDetailsProps | SecondaryDetailsProps;
+/** Union type of all possible Details component variants */
+export type DetailsProps = PrimaryDetailsProps | SecondaryDetailsProps | TertiaryDetailsProps
+
+/**
+ * A collapsible details component that supports three variants: primary, secondary, and tertiary.
+ * Each variant has a different visual style and structure.
+ * 
+ * @param props - The component props
+ * @returns A details element with collapsible content
+ * 
+ * @category Component
+ */
+export function Details(props: DetailsProps): React.ReactElement {
+    const { children, label } = props;
 
-export function Details(props: DetailsProps) {
-    let title = "";
-    const {children, label} = props;
+    let title
 
-    if (props.kind === "secondary") {
+    const isDeepKind = ["secondary", "tertiary"].includes(props.kind || "");
+
+    if (isDeepKind && "title" in props) {
         title = props.title;
     }
 
     const kind = props.kind || "primary";
 
-    return <details className={`
-        ${$details.host} 
-        ${kind === "secondary" && $details.host$$secondary}
-   `}>
-        <summary className={`
-        ${$details.summary} 
-        ${kind === "secondary" && $details.summary$$secondary}
-   `}>
-            {kind === "primary" && <>
-                <$Icon/>
-                <$Label>
-                    {label}
-                </$Label>
-            </>}
-            {kind === "secondary" && <>
+    return <details
+        part="details"
+        className={`${cn.DetailsHost} ${props.className || ""}`}
+        data-kind={props.kind}
+    >
+        <summary part="summary">
+            {kind === "primary" && (
+                <>
+                    {props.icon || <$Icon />}
+                    <div part="summary-deep-label">
+                        {label}
+                    </div>
+                </>
+            )}
+
+            {isDeepKind && (
                 <div>
-                    <div className={$details.summaryDeep}>
-                        <$IconDeep/>
-                        <div className={$details.summaryDeep$text}>
+                    <div part="summary-deep">
+                        {props.icon || <$IconDeep />}
+                        <div part="summary-deep-text">
                             {title}
                         </div>
                     </div>
-                    <$Label>
+                    <div part="summary-deep-label">
                         {label}
-                    </$Label>
-                </div>
-                <$Icon/>
-            </>}
+                    </div>
+                </div> 
+            )}
+            {isDeepKind && <$Icon />}
         </summary>
 
-        <div className={`
-            ${$details.content}
-            ${kind === "secondary" && $details.content$$secondary}
-        `}>
+        <div part="content">
             {children}
         </div>
     </details>
 }
 
 function $Icon() {
-    return <div className={$details.icon}>
+    return <div part="icon">
         <svg
             // TODO: bad solution
             data-icon="true"
@@ -107,16 +151,9 @@ function $IconDeep() {
         </g>
         <defs>
             <clipPath id="clip0_1689_2180">
-                <rect width={24} height={24} fill="white"/>
+                <rect width={24} height={24} fill="white" />
             </clipPath>
         </defs>
     </svg>
 }
 
-function $Label({children}: {
-    children?: React.ReactNode
-}) {
-    return <div className={$details.label}>
-        {children}
-    </div>
-}

package/src/writer/Example/index.tsx

@@ -0,0 +1,5 @@
+import React from "react"
+
+export function Example() {
+    return <div>Example xD 2</div>
+}

package/src/writer/GuideCard/GuideCard.styles.tsx

@@ -1,115 +1,116 @@
-import {css} from "@linaria/core";
-
-export const $guide = {
-    host: css`
-    `,
-    host$$secondary: css`
-        //flex-grow: 1;
-        //width: 100%;
-        display: flex;
-        position: relative;
-        overflow: hidden;
-        border: .5px solid #ececf1;
-        background: linear-gradient(238deg, rgba(247, 247, 248, .5) 0%, rgba(247, 247, 248, 1) 100%);
-        border-radius: 8px;
-        padding: 16px 20px 20px;
-        z-index: 0;
-        transition: box-shadow .2s ease-in-out, background-image .2s ease;
-
-        &:hover {
-            background: linear-gradient(238deg, rgba(255, 255, 255, .5) 0%, rgba(250, 250, 250, 1) 100%);
+import { css } from "@linaria/core";
+
+export const GuideHost = css`
+    @layer defaults {
+        display: block;
+
+        &[data-kind="secondary"] {
+            display: flex;
+            position: relative;
+            overflow: hidden;
+            border: 1px solid var(--xyd-guidecard-border-color--secondary);
+            background: var(--xyd-guidecard-bgcolor--secondary);
+            border-radius: 8px;
+            padding: 24px;
+            z-index: 0;
+            transition: box-shadow .2s ease-in-out, background-image .2s ease;
+
+            &:hover {
+                background: var(--xyd-guidecard-bgcolor--secondary-hover);
+            }
+
+            &[data-size="md"] {
+                padding: 21px 25px 25px;
+            }
+        }
+
+        [part="link"] {
+            width: 100%;
+            height: 100%;
         }
-    `,
-    host$$secondary$$md: css`
-        padding: 21px 25px 25px;
-    `,
-    link: css`
-        width: 100%;
-        height: 100%;
-    `,
-    item: css`
-        border-radius: 8px;
-        display: flex;
-
-        align-items: flex-start;
-        cursor: pointer;
-        transition: opacity .15s;
-
-        &:hover {
-            [data-pointer="true"] {
-                opacity: 1;
-                transform: translate(0);
+
+        [part="item"] {
+            border-radius: 8px;
+            display: flex;
+
+            align-items: flex-start;
+            cursor: pointer;
+            transition: opacity .15s;
+
+            &:hover {
+                [part="pointer"] {
+                    opacity: 1;
+                    transform: translate(0);
+                }
             }
         }
-    `,
-    item$$secondary: css`
-        width: 100%;
-        height: 100%;
-    `,
-    icon: css`
-        line-height: 0px;
-        font-size: 24px;
-        border-radius: 8px;
-        width: 48px;
-        height: 48px;
-        display: flex;
-        justify-content: center;
-        align-items: center;
-        color: #353740;
-        border: 1px solid #ececf1;
-        background: linear-gradient(238deg, rgba(255, 255, 255, .5) 0%, rgba(250, 250, 250, 1) 100%);
-        transition: background .2s ease;
-        box-sizing: border-box;
-        flex-shrink: 0;
-    `,
-    right: css`
-        padding-left: 16px;
-        display: flex;
-        flex-direction: column;
-        gap: 4px;
-    `,
-    title: css`
-        display: flex;
-        color: #202123;
-        font-weight: 400;
-        align-items: center;
-        transition: color .15s;
-    `,
-    titleBody: css`
-        font-size: 16px;
-        line-height: 20px;
-    `,
-    titleBody$$md: css`
-        font-size: 18px;
-    `,
-    body: css`
-        font-weight: 400;
-        font-size: 14px;
-        line-height: 20px;
-
-        color: #6e6e80;
-        white-space: normal;
-        overflow: hidden;
-        text-overflow: ellipsis;
-    `,
-    body$$md: css`
-        font-size: 16px;
-    `,
-    pointer: css`
-        opacity: 0;
-        transform: translate(-4px);
-        display: flex;
-        justify-content: center;
-        transition: opacity .15s ease-in-out, transform .15s ease-in-out;
-    `
-}
+        &[data-kind="secondary"] [part="item"] {
+            width: 100%;
+            height: 100%;
+        }
+
+        [part="icon"] {
+            height: 32px;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            color: var(--xyd-guidecard-icon-color);
+            transition: background .2s ease;
+            box-sizing: border-box;
+            flex-shrink: 0;
 
+            svg {
+                width: 24px;
+                height: 24px;
+            }
+        }
+
+        [part="right"] {
+            padding-left: 16px;
+            display: flex;
+            flex-direction: column;
+            gap: 4px;
+        }
+
+        [part="title"] {
+            display: flex;
+            color: var(--xyd-guidecard-title-color);
+            align-items: center;
+            font-weight: var(--xyd-font-weight-semibold);
+            transition: color .15s;
+        }
+
+        [part="title-body"] {
+        }
+        &[data-size="md"] [part="title-body"] {
+        }
+
+        [part="body"] {
+            font-weight: var(--xyd-font-weight-normal);
+
+            color: var(--xyd-guidecard-color);
+            white-space: normal;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }
+        &[data-size="md"] [part="body"] {
+        }
+
+        [part="pointer"] {
+            opacity: 0;
+            transform: translate(-4px);
+            display: flex;
+            justify-content: center;
+            transition: opacity .15s ease-in-out, transform .15s ease-in-out;
+        }
+    }
+`;
 
-export const $list = {
-    host: css`
+export const GuideListHost = css`
+    @layer defaults {
         display: grid;
         grid-template-columns: 1fr 1fr;
         justify-content: center;
-        gap: 30px;
-    `
-}
+        gap: 24px;
+    }
+`;

package/src/writer/GuideCard/GuideCard.tsx

@@ -1,69 +1,95 @@
 import React from "react"
 
-import {$guide, $list} from "./GuideCard.styles";
+import * as cn from "./GuideCard.styles";
 
+/**
+ * Props for the GuideCard component
+ */
 export interface GuideCardProps {
+    /** Content to be displayed in the card body */
     children: React.ReactNode;
+
+    /** URL the card links to */
     href: string
+
+    /** Title displayed at the top of the card */
     title: string;
+
+    /** Optional icon displayed to the left of the content */
     icon?: React.ReactNode;
+
+    /** Visual style variant of the card */
     kind?: "secondary"
+
+    /** Size variant of the card */
     size?: "sm" | "md"
+
+    /** Additional CSS class names to apply to the card */
+    className?: string
+
+    /** Additional props to pass to the link element */
+    as?: React.ElementType
 }
 
+/**
+ * A card component that displays content with a title and optional icon.
+ * The entire card is clickable and links to the specified URL.
+ * 
+ * @category Component
+ */
 export function GuideCard({
-                              children,
-                              href,
-                              icon,
-                              title,
-                              kind,
-                              size,
+    children,
+    href,
+    icon,
+    title,
+    kind,
+    size,
+    className,
+    as,
+}: GuideCardProps) {
+    const Link = as || $Link
 
-                          }: GuideCardProps) {
-    return <div className={`
-        ${$guide.host}
-        ${kind === "secondary" && $guide.host$$secondary}
-        ${kind === "secondary" && size == "md" && $guide.host$$secondary$$md}
-    `}>
-        <a className={$guide.link} href={href}>
-            <div className={`
-                ${$guide.item}
-                ${kind === "secondary" && $guide.item$$secondary}
-            `}>
-                {icon && <div className={$guide.icon}>
+    return <xyd-guidecard
+        className={`${cn.GuideHost} ${className || ""}`}
+        data-kind={kind}
+        data-size={size}
+    >
+        <Link part="link" href={href}>
+            <div part="item">
+                {icon && <div part="icon">
                     {icon}
                 </div>}
-                <div className={$guide.right}>
-                    <div className={$guide.title}>
-                        <div className={`
-                            ${$guide.title} 
-                            ${$guide.titleBody}
-                            ${size == "md" && $guide.titleBody$$md}
-                        `}>
+                <div part="right">
+                    <div part="title">
+                        <div part="title-body">
                             {title}
                         </div>
-                        <$Pointer/>
+                        <$Pointer />
                     </div>
-                    <div className={`
-                        ${$guide.body}
-                        ${size == "md" && $guide.body$$md}
-                    `}>
+                    <div part="body">
                         {children}
                     </div>
                 </div>
             </div>
-        </a>
-    </div>
+        </Link>
+    </xyd-guidecard>
 }
 
-GuideCard.List = function GuideCardList({children}: { children: React.ReactNode }) {
-    return <div className={$list.host}>
+/**
+ * A container component for grouping multiple GuideCard components.
+ * Provides consistent spacing and layout for a list of guide cards.
+ */
+GuideCard.List = function GuideCardList({ children }: { children: React.ReactNode }) {
+    return <xyd-guidecard-list className={cn.GuideListHost}>
         {children}
-    </div>
+    </xyd-guidecard-list>
 }
 
+/**
+ * Internal component that renders the arrow pointer icon.
+ */
 function $Pointer() {
-    return <div data-pointer="true" className={$guide.pointer}>
+    return <div part="pointer">
         <svg
             xmlns="http://www.w3.org/2000/svg"
             width={24}
@@ -78,4 +104,13 @@ function $Pointer() {
             />
         </svg>
     </div>
+}
+
+function $Link({ href, children, ...rest }) {
+    return <a
+        href={href}
+        {...rest}
+    >
+        {children}
+    </a>
 }