Styled system + styling + slot documentation (#549)

gsoft-inc · Dec 11, 2024 · b77ed2b · b77ed2b
2 parents 4da516e + 82e6ea5
commit b77ed2b
Show file tree

Hide file tree

Showing 45 changed files with 970 additions and 431 deletions.
diff --git a/apps/docs/.eslintrc.json b/apps/docs/.eslintrc.json
@@ -17,6 +17,7 @@
         "Collapsible": true,
         "Expand": true,
         "TokenTable": true,
+        "PropsReferenceTable": true,
         "MotionPreview": true,
         "Figure": true,
         "Footnote": true,

diff --git a/apps/docs/app/home.css b/apps/docs/app/home.css
@@ -171,11 +171,11 @@ a.hd-home-sample__item:hover::after {
 .hd-home-sample__title-tag {
     align-self: center;
     border-radius: var(--hd-border-radius-sm);
-    background-color: var(--hd-color-accent-surface-strong);
-    color: var(--hd-white);
+    color: var(--hd-color-accent-text);
+    background-color: var(--hd-color-accent-surface);
     font-size: 0.75rem;
     font-weight: 400;
-    padding: var(--hd-space-05);
+    padding: 0.125rem var(--hd-space-05);
 }
 
 .hd-home-sample__tagline {

diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
@@ -3,6 +3,8 @@ import { EnvironmentContextProvider } from "@/context/env/EnvironmentProvider";
 import { FeatureFlagProvider } from "@/context/feature/FeatureFlagProvider";
 import { RACProvider } from "@/context/rac/RACProvider";
 import { ThemeProvider } from "@/context/theme/ThemeProvider";
+import "@hopper-ui/tokens/fonts.css";
+import "@hopper-ui/tokens/tokens.css";
 import type { ReactNode } from "react";
 import "./globals.css";
 import "./layout.css";

diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
@@ -12,7 +12,6 @@ import {
     SelectArrowIcon,
     TypescriptIcon
 } from "@/components/icon";
-import "@hopper-ui/tokens/fonts.css";
 import Link from "next/link";
 import "./home.css";
 import { ComponentsCard } from "./ui/home-page/ComponentsCard";

diff --git a/apps/docs/app/ui/components/propTable/PropTableRender.tsx b/apps/docs/app/ui/components/propTable/PropTableRender.tsx
@@ -43,10 +43,10 @@ const columns: ColumnDef<Item>[] = [
             const { name, type, required } = info.getValue() as { name: ReactNode; type: ReactNode; required: boolean };
 
             return (
-                <dt className="hd-props-table__description-term">
+                <div className="hd-props-table__description-term">
                     <div className="hd-props-table__name">{name}{!required && "?"}</div>
                     <div className="hd-props-table__type">{type}</div>
-                </dt>
+                </div>
             );
         }
     },
@@ -58,12 +58,12 @@ const columns: ColumnDef<Item>[] = [
             const { description, defaultValue } = info.getValue() as { description: ReactNode; defaultValue: string };
 
             return (
-                <dl className="hd-props-table__description-list">
+                <div className="hd-props-table__description-list">
                     <div className="hd-props-table__description">{description}</div>
                     {defaultValue !== "" && (
                         <div className="hd-props-table__default-value"><em>Defaults to <ColoredDefaultValue defaultValue={defaultValue} />.</em></div>
                     )}
-                </dl>
+                </div>
             );
         }
     }
@@ -87,7 +87,7 @@ export const PropTableRender = ({ items }: { items: Item[] }) => {
 
     return (
         <div className="hd-table hd-props-table">
-            <dl className="hd-props-table__tbody">
+            <div className="hd-props-table__tbody">
                 {table.getRowModel().rows.map(row => (
                     <div key={row.id} className="hd-table__row hd-props-table__row">
                         {row.getVisibleCells().map(cell => {
@@ -102,7 +102,7 @@ export const PropTableRender = ({ items }: { items: Item[] }) => {
                         )}
                     </div>
                 ))}
-            </dl>
+            </div>
         </div>
     );
 };
diff --git a/apps/docs/app/ui/components/propsReferenceTable/PropsReferenceTable.tsx b/apps/docs/app/ui/components/propsReferenceTable/PropsReferenceTable.tsx
@@ -0,0 +1,45 @@
+import Table, { type TableProps } from "@/components/table/Table";
+import Link from "next/link";
+import type { ReactNode } from "react";
+import "./propsReferenceTable.css";
+
+const ScaleLinks: Record<string, ReactNode> = {
+    "color-scale": <Link href="/tokens/semantic/color" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Colors</Link>,
+    "elevation-scale": <Link href="/tokens/semantic/elevation" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Elevation</Link>,
+    "dimension-scale": <Link href="/tokens/core/dimensions" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Dimensions</Link>,
+    "spacing-scale": <Link href="/tokens/semantic/space" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Spacing</Link>,
+    "shape-scale": <Link href="/tokens/semantic/space" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Shape</Link>,
+    "typography-scale": <Link href="/tokens/semantic/typography" target="_blank" style={{ color: "var(--hd-color-accent-text)" }}>Typography</Link>
+};
+
+function toScaleLink(scale: string) {
+    return ScaleLinks[scale] ?? scale;
+}
+
+function toRowValues([propName, cssProperty, scale, supports]: string[]): TableProps["data"][number] {
+    return {
+        "Prop": propName,
+        "CSS property": cssProperty,
+        "Scale": toScaleLink(scale),
+        "Supports": supports
+    };
+}
+
+export interface PropsReferenceTableProps {
+    rows: string[][];
+}
+
+export function PropsReferenceTable({ rows }: PropsReferenceTableProps) {
+    return (
+        <Table
+            className="hd-props-reference-table"
+            head={[
+                "Prop",
+                "CSS property",
+                "Scale",
+                "Supports"
+            ]}
+            data={rows.map(x => toRowValues(x))}
+        />
+    );
+}
diff --git a/apps/docs/app/ui/components/propsReferenceTable/propsReferenceTable.css b/apps/docs/app/ui/components/propsReferenceTable/propsReferenceTable.css
@@ -0,0 +1,3 @@
+.hd-props-reference-table {
+    table-layout: fixed;
+}
diff --git a/apps/docs/app/ui/components/simpleTable/SimpleTable.tsx b/apps/docs/app/ui/components/simpleTable/SimpleTable.tsx
@@ -13,7 +13,7 @@ export default async function SimpleTable({ "aria-label": ariaLabel, headers, da
             <thead>
                 <tr>
                     {headers.map((header, index) => {
-                        const classNames = clsx("hd-table__column", { "hd-table__colum--right": index === headers.length - 1 && lastColumnAlignment === "right" });
+                        const classNames = clsx("hd-table__column", { "hd-table__column--right": index === headers.length - 1 && lastColumnAlignment === "right" });
 
                         return (
                             // eslint-disable-next-line react/no-array-index-key

diff --git a/apps/docs/app/ui/layout/mobileMenu/mobileMenu.css b/apps/docs/app/ui/layout/mobileMenu/mobileMenu.css
@@ -96,10 +96,10 @@
 .hd-mobile-menu-nav-tag {
     align-self: center;
     border-radius: var(--hd-border-radius-sm);
-    background-color: var(--hd-color-accent-surface-strong);
-    color: var(--hd-white);
+    color: var(--hd-color-accent-text);
+    background-color: var(--hd-color-accent-surface);
     font-size: 0.75rem;
-    padding: var(--hd-space-05);
+    padding: 0.125rem var(--hd-space-05);
 }
 
 .hd-mobile-menu--opening {

diff --git a/apps/docs/app/ui/layout/nav/nav.css b/apps/docs/app/ui/layout/nav/nav.css
@@ -58,9 +58,9 @@
 /* Tag */
 .hd-nav__link-tag {
     border-radius: var(--hd-border-radius-sm);
-    background-color: var(--hd-color-accent-surface-strong);
-    color: var(--hd-white);
-    font-size: 0.75rem;
-    padding: var(--hd-space-05);
+    color: var(--hd-color-accent-text);
+    background-color: var(--hd-color-accent-surface);
+    font-size: 0.825rem;
+    padding: 0.125rem var(--hd-space-05);
     margin-inline-start: var(--hd-space-05);
 }
diff --git a/apps/docs/app/ui/tokens/preview/Preview.tsx b/apps/docs/app/ui/tokens/preview/Preview.tsx
@@ -1,6 +1,6 @@
 import "@hopper-ui/tokens/fonts.css";
-import "./preview.css";
 import type { CSSProperties, ReactNode } from "react";
+import "./preview.css";
 
 interface PreviewProps {
     category?: string;
@@ -80,7 +80,7 @@ const Preview = ({ category, name, value }: PreviewProps) => {
             };
             if (matchingPaddingKeyword) {
                 preview = {
-                    style: { padding: value },
+                    style: { padding: value, justifySelf: "end" },
                     className: `hd-preview--semantic-size hd-preview--${matchingPaddingKeyword}`
                 };
             }
@@ -92,7 +92,7 @@ const Preview = ({ category, name, value }: PreviewProps) => {
             }
             if (matchingStackKeyword) {
                 preview = {
-                    style: { padding: `0 0 ${value} 0` },
+                    style: { padding: `0 0 ${value} 0`, justifySelf: "end" },
                     className: `hd-preview--semantic-size hd-preview--${matchingStackKeyword}`
                 };
             }

diff --git a/apps/docs/app/ui/tokens/table/IconSpecTable.tsx b/apps/docs/app/ui/tokens/table/IconSpecTable.tsx
@@ -13,11 +13,14 @@ interface IconSpecTableProps {
 }
 
 const IconSpecTable = ({ data }: IconSpecTableProps) => {
-    return <Table className="hd-table--icon-spec"
-        head={["Anatomy", "Small", "Medium", "Large"]}
-        data={data}
-        ariaLabel="Icons specs"
-    />;
+    return (
+        <Table
+            className="hd-table--icon-spec"
+            head={["Anatomy", "Small", "Medium", "Large"]}
+            data={data}
+            ariaLabel="Icons specs"
+        />
+    );
 };
 
 export default IconSpecTable;
diff --git a/apps/docs/app/ui/tokens/table/TokenTable.tsx b/apps/docs/app/ui/tokens/table/TokenTable.tsx
@@ -3,34 +3,79 @@ import Table from "@/components/table/Table";
 import Preview from "@/app/ui/tokens/preview/Preview";
 import Code from "@/components/code/Code";
 
+import type { ReactNode } from "react";
 import "./tokenTable.css";
 
 interface TableProps {
     category: string;
     noPreview?: boolean;
+    tokenType?: "core" | "semantic" | null;
     data: {
         name: string;
         value: string;
     }[];
 }
 
-const TokenTable = ({ category, data, noPreview }: TableProps) => {
+function formatStyledSystemName(name: string, tokenType: "core" | "semantic" | null) {
+    let prefix = "";
+    if (tokenType === "core") {
+        prefix = "core_";
+    } else if (name?.includes("dataviz")) {
+        prefix = "dataviz_";
+    }
+
+    const formattedName = name
+        .replace("hop-", "")
+        .replace("-border", "")
+        .replace("-surface", "")
+        .replace("-text", "")
+        .replace("-icon", "")
+        .replace("elevation-", "")
+        .replace("shape-", "")
+        .replace("space-", "")
+        .replace("border-", "")
+        .replace("radius-", "")
+        .replace("border-", "")
+        .replace("dataviz-", "")
+        .replace("shadow-", "")
+        .replace("font-family-", "")
+        .replace("font-size-", "")
+        .replace("font-weight-", "")
+        .replace("line-height-", "")
+    ;
+
+    return `${prefix}${formattedName}`;
+}
+
+const TokenTable = ({ category, data, noPreview = false, tokenType }: TableProps) => {
     const formattedData = data.map(token => {
         const { name, value } = token;
-
-        return {
+        const values: Record<string, ReactNode> = {
             name: <Code value={`--${name}`}>{`--${name}`}</Code>,
+            styledSystemValue: tokenType && formatStyledSystemName(name, tokenType),
             value: value,
             preview: !noPreview && <Preview value={value} name={name} category={category} />
         };
-    });
 
+        if (!tokenType) {
+            delete values.styledSystemValue;
+        }
+
+        if (noPreview) {
+            delete values.preview;
+        }
+
+        return values;
+    });
+    const columns = ["Name", tokenType && "Styled-System Value", "Value", !noPreview && "Preview"].filter(Boolean) as string[];
 
-    return <Table head={["Name", "Value", !noPreview && "Preview"]}
-        data={formattedData}
-        lastColumnAlignment="right"
-        ariaLabel="Tokens"
-    />;
+    return (
+        <Table head={columns}
+            data={formattedData}
+            lastColumnAlignment="right"
+            ariaLabel="Tokens"
+        />
+    );
 };
 
 export default TokenTable;
diff --git a/apps/docs/app/ui/tokens/table/TypographyTable.tsx b/apps/docs/app/ui/tokens/table/TypographyTable.tsx
@@ -44,7 +44,7 @@ const TypographyTable = ({ type, data }: TypographyTableProps) => {
                     !hasNoSizes && "Size",
                     "Values",
                     "Preview"
-                ]}
+                ].filter(Boolean) as string[]}
                 data={listItems}
                 className={clsx("hd-typo-table", { "hd-typo-table--has-no-sizes": hasNoSizes })}
                 ariaLabel="Typography tokens"

diff --git a/apps/docs/app/ui/tokens/table/TypographyVariantTable.tsx b/apps/docs/app/ui/tokens/table/TypographyVariantTable.tsx
@@ -33,7 +33,8 @@ const TypographyVariantTable = ({ type, data }: TypographyVariantTableProps) =>
     });
 
     return (
-        <Table head={["Name", "Value", "Preview"]}
+        <Table
+            head={["Name", "Value", "Preview"]}
             className="hd-typo-table"
             data={listItems}
             ariaLabel="Typography"

diff --git a/apps/docs/app/ui/tokens/tableSection/TableSection.tsx b/apps/docs/app/ui/tokens/tableSection/TableSection.tsx
@@ -1,8 +1,7 @@
-"use client";
-
 import TokenTable from "@/app/ui/tokens/table/TokenTable.tsx";
 
 import "@hopper-ui/tokens/fonts.css";
+import { useMemo } from "react";
 
 interface TokenProps {
     name: string;
@@ -14,18 +13,23 @@ interface TableSectionProps {
     categories: string[];
     excludedCategories?: string[];
     categoryKey: string;
+    tokenType?: "core" | "semantic";
 }
 
-const TableSection = ({ tokens, categories, excludedCategories, categoryKey }: TableSectionProps) => {
-    const categoryTokens = tokens.filter(token => {
-        const excludedCategoryTokens = excludedCategories?.some(category => token.name.includes(category));
+const TableSection = ({ tokens, categories, excludedCategories, categoryKey, tokenType }: TableSectionProps) => {
+    const categoryTokens = useMemo(() => {
+        return tokens.filter(token => {
+            const excludedCategoryTokens = excludedCategories?.some(category => token.name.includes(category));
 
-        return categories.some(category => token.name.includes(category)) && !excludedCategoryTokens;
-    });
+            return categories.some(category => token.name.includes(category)) && !excludedCategoryTokens;
+        });
+    }, [tokens, categories, excludedCategories]);
 
-    return <div className="hd-table-section">
-        <TokenTable category={categoryKey} data={categoryTokens} />
-    </div>;
+    return (
+        <div className="hd-table-section">
+            <TokenTable tokenType={tokenType} category={categoryKey} data={categoryTokens} />
+        </div>
+    );
 };
 
 export default TableSection;
diff --git a/apps/docs/components/mdx/components.tsx b/apps/docs/components/mdx/components.tsx
@@ -33,6 +33,7 @@ import { ComponentCodeWrapper } from "@/app/ui/components/componentExample/Compo
 import type { ComponentExampleProps } from "@/app/ui/components/componentExample/ComponentExample.tsx";
 import ComponentPreview from "@/app/ui/components/componentExample/ComponentPreview.tsx";
 import type { MigrateGuideProps } from "@/app/ui/components/migrateGuide/MigrateGuide.tsx";
+import { PropsReferenceTable } from "@/app/ui/components/propsReferenceTable/PropsReferenceTable";
 import type { PropTableProps } from "@/app/ui/components/propTable/PropTable.tsx";
 import SimpleTable from "@/app/ui/components/simpleTable/SimpleTable";
 
@@ -60,6 +61,7 @@ export const components = {
     BreakpointTable: BreakpointTable,
     Footnote: Footnote,
     TokenTable: TokenTable,
+    PropsReferenceTable: PropsReferenceTable,
     TypographyTable: TypographyTable,
     TypographyVariantTable: TypographyVariantTable,
     IconTable: IconTable,