@xyd-js/components 0.1.0-xyd.10 → 0.1.0-xyd.13

package/src/writer/GuideCard/GuideCard.tsx

@@ -2,68 +2,94 @@ import React from "react"
 
 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={`
-        ${cn.GuideHost}
-        ${kind === "secondary" && cn.GuideHostSecondary}
-        ${kind === "secondary" && size == "md" && cn.GuideHostSecondaryMd}
-    `}>
-        <a className={cn.GuideLink} href={href}>
-            <div className={`
-                ${cn.GuideItem}
-                ${kind === "secondary" && cn.GuideItemSecondary}
-            `}>
-                {icon && <div className={cn.GuideIcon}>
+    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={cn.GuideRight}>
-                    <div className={cn.GuideTitle}>
-                        <div className={`
-                            ${cn.GuideTitle} 
-                            ${cn.GuideTitleBody}
-                            ${size == "md" && cn.GuideTitleBodyMd}
-                        `}>
+                <div part="right">
+                    <div part="title">
+                        <div part="title-body">
                             {title}
                         </div>
-                        <Pointer/>
+                        <$Pointer />
                     </div>
-                    <div className={`
-                        ${cn.GuideBody}
-                        ${size == "md" && cn.GuideBodyMd}
-                    `}>
+                    <div part="body">
                         {children}
                     </div>
                 </div>
             </div>
-        </a>
-    </div>
+        </Link>
+    </xyd-guidecard>
 }
 
-GuideCard.List = function GuideCardList({children}: { children: React.ReactNode }) {
-    return <div className={cn.GuideListHost}>
+/**
+ * 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>
 }
 
-function Pointer() {
-    return <div data-pointer="true" className={cn.GuidePointer}>
+/**
+ * Internal component that renders the arrow pointer icon.
+ */
+function $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>
 }

package/src/writer/Heading/Heading.styles.tsx

@@ -1,77 +1,93 @@
-import {css} from "@linaria/core";
+import { css } from "@linaria/core";
 
 export const HeadingHost = css`
-    line-height: 40px;
-    font-weight: 600;
-
-    position: relative;
-    display: inline-block;
-    margin: 0;
-    padding: 0 24px 0 0;
-    scroll-margin-top: 30px;
-    cursor: pointer;
-
-    &:hover {
-        svg {
-            opacity: 1;
+    @layer defaults {
+        color: var(--xyd-heading-color);
+        line-height: var(--xyd-line-height-xlarge);
+        font-weight: var(--xyd-font-weight-semibold);
+
+        position: relative;
+        display: table;
+        margin: 0;
+        padding: 0 24px 0 0;
+        scroll-margin-top: 30px;
+        cursor: default;
+
+        &[id] {
+            cursor: pointer;
+        }
+        &[data-noanchor="true"] {
+            cursor: default;
         }
-    }
-`;
-
-export const HeadingH1 = css`
-    font-size: 36px;
 
-    code {
-        font-size: 30px;
-    }
-`;
+        &[data-has-label="true"] {
+            display: flex;
+            align-items: center;
+            gap: 8px;
 
-export const HeadingH2 = css`
-    font-size: 30px;
+            xyd-badge {
+                font-size: var(--xyd-font-size-xsmall);
+                line-height: var(--xyd-line-height-xsmall);
+                letter-spacing: 2px;
+            }
+        }
 
-    code {
-        font-size: 24px;
-    }
-`;
+        &:hover {
+            svg {
+                opacity: 1;
+            }
+        }
 
-export const HeadingH3 = css`
-    font-size: 26px;
+        &[data-kind="muted"] {
+            color: var(--xyd-heading-color--muted);
+            cursor: default;
+            font-weight: var(--xyd-font-weight-medium);
+        }
 
-    code {
-        font-size: 22px;
-    }
-`;
+        &[data-size="1"] {
+            font-size: var(--xyd-font-size-2xl);
+            line-height: var(--xyd-line-height-2xl);
+        }
 
-export const HeadingH4 = css`
-    font-size: 22px;
+        &[data-size="2"] {
+            font-size: var(--xyd-font-size-xxlarge);
+            line-height: var(--xyd-line-height-xxlarge);
+        }
 
-    code {
-        font-size: 18px;
-    }
-`;
+        &[data-size="3"] {
+            font-size: var(--xyd-font-size-xlarge);
+            line-height: var(--xyd-line-height-xlarge);
+        }
 
-export const HeadingH5 = css`
-    font-size: 18px;
+        &[data-size="4"] {
+            font-size: var(--xyd-font-size-large);
+            line-height: var(--xyd-line-height-large);
+        }
 
-    code {
-        font-size: 14px;
-    }
-`;
+        &[data-size="5"] {
+            font-size: var(--xyd-font-size-medium);
+            line-height: var(--xyd-line-height-medium);
+        }
 
-export const HeadingH6 = css`
-    font-size: 16px;
+        &[data-size="6"] {
+            font-size: var(--xyd-font-size-small);
+            line-height: var(--xyd-line-height-small);
+        }
 
-    code {
-        font-size: 12px;
+        [part="icon"] {
+            position: absolute;
+            top: 50%;
+            right: 0;
+            margin-top: -6px;
+            opacity: 0;
+            color: var(--xyd-heading-icon-color);
+            transition: opacity .15s ease;
+        }
+        &[data-active="true"] {
+            [part="icon"] {
+                opacity: 1;
+            }
+        }
     }
 `;
 
-export const HeadingLink = css`
-    position: absolute;
-    top: 50%;
-    right: 0;
-    margin-top: -6px;
-    opacity: 0;
-    color: #7051d4;
-    transition: opacity .15s ease;
-`;

package/src/writer/Heading/Heading.tsx

@@ -1,47 +1,117 @@
-import React, {useRef} from "react"
+import React, { } from "react"
 
 import * as cn from "./Heading.styles";
+import { Badge } from "writer";
 
+/**
+ * Props for the Heading component
+ * @interface HeadingProps
+ */
 export interface HeadingProps {
+    /** Content to be rendered inside the heading */
     children: React.ReactNode
+
+    /** The size of the heading (1-6, corresponding to h1-h6) */
     size: 1 | 2 | 3 | 4 | 5 | 6
+
+    /** Optional HTML element to render as (div or span) */
     as?: "div" | "span"
+
+    /** Optional ID for the heading element */
     id?: string
+
+    /** Optional visual style variant */
+    kind?: "muted"
+
+    /** Optional click handler */
     onClick?: () => void
+
+    /** Optional additional CSS class name */
+    className?: string
+
+    /** Optional active state */
+    active?: boolean
+
+    /** Optional label for the heading */
+    label?: string
+
+    /** Optional subtitle for the heading */
+    subtitle?: string
+
+    /** Optional to hide the anchor icon */
+    noanchor?: boolean
+
+    /** Optional ref for the heading element */
+    ref?: React.RefObject<HTMLHeadingElement>
+
+    style?: React.CSSProperties
 }
 
-export function Heading({children, size = 1, as, id, onClick}: HeadingProps) {
+/**
+ * A flexible heading component that can render as any heading level (h1-h6) or as a div/span
+ * 
+ * @category Component
+ */
+export function Heading(props: HeadingProps) {
+    const {
+        children,
+        size = 1,
+        as,
+        id,
+        onClick,
+        className,
+        kind,
+        active,
+        label,
+        subtitle,
+        noanchor,
+        ref,
+        style,
+    } = props
     let HeadingComponent = as ? as : `h${size}` as "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
 
-    const obRef = useRef<HTMLAnchorElement>(null)
-
-    return <HeadingComponent
-        className={`
-            ${cn.HeadingHost}
-            ${size === 1 && cn.HeadingH1}
-            ${size === 2 && cn.HeadingH2}
-            ${size === 3 && cn.HeadingH3}
-            ${size === 4 && cn.HeadingH4}
-            ${size === 5 && cn.HeadingH5}
-            ${size === 6 && cn.HeadingH6}
-            xyd_comp-comp-heading
-        `}
-        onClick={onClick}
-    >
-        {children}
+    return <>
+        <HeadingComponent
+            style={style || undefined}
+            className={` ${cn.HeadingHost}  ${className || ''}`}
+            data-size={size}
+            data-kind={kind}
+            data-has-label={String(label ? "true" : "false")}
+            data-noanchor={String(noanchor || "false")}
+            data-active={String(active || "false")}
+            onClick={noanchor ? undefined : onClick}
+            id={id}
+            ref={ref}
+        >
+            {children}
+
+            {label && <Badge size="sm">{label}</Badge>}
+
+            {id && !noanchor && <$Anchor />}
+        </HeadingComponent>
 
-        {id && <Anchor/>}
-    </HeadingComponent>
+        {
+            subtitle ? <Heading
+                {...props}
+                size={4}
+                kind="muted"
+                subtitle={undefined} 
+                label={undefined}
+            >
+                {subtitle}
+            </Heading> : null
+        }
+    </>
 }
 
-function Anchor() {
+function $Anchor() {
     return <svg
+        part="icon"
         xmlns="http://www.w3.org/2000/svg"
         width={15}
         height={15}
         fill="currentColor"
         viewBox="0 0 24 24"
-        className={cn.HeadingLink}
         role="presentation"
     >
         <path

package/src/writer/Hr/Hr.styles.tsx

@@ -1,5 +1,7 @@
 import {css} from "@linaria/core";
 
 export const HrHost = css`
-    border-color: rgb(229 229 229 / 0.7);
+    @layer defaults {
+        border: 0.5px solid var(--xyd-hr-border-color);
+    }
 `;

package/src/writer/Hr/Hr.tsx

@@ -3,11 +3,8 @@ import React from "react"
 import * as cn from "./Hr.styles";
 
 export interface HrProps {
-    children: React.ReactNode;
 }
 
-export function Hr({children}: HrProps) {
-    return <hr className={cn.HrHost}>
-        {children}
-    </hr>
+export function Hr() {
+    return <hr part="hr" className={cn.HrHost}/>
 }

package/src/writer/Icon/Icon.tsx

@@ -0,0 +1,48 @@
+import React, {createContext, ReactElement, SVGProps, use} from "react";
+import parse from 'html-react-parser';
+
+// TODO: html-react-parser is not the best choice, but it works for now
+
+export const IconProvider = createContext({
+    iconSet: {}
+})
+
+interface IconProps {
+    name: string;
+    size?: number;
+    color?: string;
+}
+
+export function Icon(props: IconProps): ReactElement | null {
+    const {name, size = 24, color} = props
+
+    const iconProvider = use(IconProvider)
+    const iconSet = iconProvider?.iconSet
+
+    if (!iconSet) {
+        return null
+    }
+
+    const ico = iconSet[name]
+    if (!ico || !ico.svg) {
+        return null
+    }
+
+    const icon = parse(ico.svg) as ReactElement<SVGProps<SVGSVGElement>>
+    if (React.isValidElement(icon)) {
+        return React.cloneElement(icon, {
+            width: size,
+            height: size,
+            color: color || icon.props.color || 'currentColor',
+            style: {
+                width: size,
+                height: size,
+                color: color || icon.props.color || 'currentColor',
+            }
+        })
+    }
+
+    return null
+}
+
+

package/src/writer/Icon/index.ts

@@ -0,0 +1 @@
+export * from "./Icon"

package/src/writer/Image/Image.styles.tsx

@@ -0,0 +1,9 @@
+import { css } from "@linaria/core"
+
+export const ImageHost = css`
+    @layer defaults {
+        width: 100%;
+        border-radius: 16px;
+        box-shadow: 0 2px 16px rgba(0,0,0,0.06);
+    }
+`;

package/src/writer/Image/Image.tsx

@@ -0,0 +1,19 @@
+
+
+import React from 'react';
+
+import * as cn from "./Image.styles"
+
+export interface ImageProps {
+    src: string
+    alt: string
+    style?: React.CSSProperties
+}
+
+export function Image(props: ImageProps) {
+    return <img
+        src={props.src}
+        alt={props.alt}
+        className={cn.ImageHost}
+    />
+}

package/src/writer/Image/index.ts

@@ -0,0 +1 @@
+export { Image } from "./Image"

package/src/writer/List/List.styles.tsx

@@ -0,0 +1,47 @@
+import { css } from '@linaria/core'
+
+export default {
+    List: css`
+        @layer defaults {
+            list-style: none;
+            margin: 0;
+            padding: 0;
+
+            ol& {
+                list-style-type: decimal;
+                padding-inline-start: 1.625em;
+            }
+        }
+    `,
+    Item: css`
+        @layer defaults {
+            ul & {
+                margin-bottom: 0.5rem;
+                position: relative;
+                padding-inline-start: .375em;
+                padding-left: 2em !important;
+            }
+
+            /*  TODO: IN THE FUTURE BETTER SOLUTION IS NEEDED */
+            xyd-grid-decorator ul & {
+                padding-left: 0 !important;
+            }
+
+            ul &::before {
+                content: "";
+                width: .375em;
+                height: .375em;
+                position: absolute;
+                top: 0.5em;
+                left: .5em;
+                border-radius: 50%;
+                background-color: var(--xyd-list-item-bgcolor);
+            }
+
+            ol &::marker {
+                padding-inline-start: .375em;
+                color: var(--xyd-list-marker-color);
+            }
+        }
+    `
+}

package/src/writer/List/List.tsx

@@ -0,0 +1,29 @@
+import React from "react"
+
+import cn from "./List.styles";
+
+export interface ListProps {
+    children: React.ReactNode;
+}
+
+export function List({ children }: ListProps) {
+    return <ul className={cn.List}>
+        {children}
+    </ul>
+}
+
+export function ListOl({ children }: ListProps) {
+    return <ol className={cn.List}>
+        {children}
+    </ol>
+}
+
+export interface ListItemProps {
+    children: React.ReactNode;
+}
+
+function ListItem({ children }: ListItemProps) {
+    return <li className={cn.Item}>{children}</li>
+}
+
+List.Item = ListItem;

package/src/writer/List/index.ts

@@ -0,0 +1,4 @@
+export {
+    List,
+    ListOl
+} from "./List";