[docs] Rewrite CardList docs (#7112)

palantir · Dec 10, 2024 · b95a86d · b95a86d · svc-palantir-github · Dec 10, 2024
1 parent d09e8c9
commit b95a86d
Show file tree

Hide file tree

Showing 5 changed files with 187 additions and 37 deletions.
diff --git a/packages/core/src/components/card-list/card-list.md b/packages/core/src/components/card-list/card-list.md
@@ -4,48 +4,48 @@ tag: new
 
 @# Card List
 
-__CardList__ is a lightweight wrapper around the [__Card__](#core/components/card) component. It can be used to
-visually group together cards in a list without any excess visual weight around or between them. Long lists may
-be styled with CSS to scroll vertically.
+**CardList** is a lightweight wrapper around the [**Card**](#core/components/card) component.
+It groups cards visually into a list without adding extra visual weight or spacing between them.
+Long lists can be styled with CSS for vertical scrolling.
 
-@reactExample CardListExample
-
-@## Usage
+@## Import
 
 ```tsx
-import { Card, CardList } from "@blueprintjs/core";
-
-<CardList>
-    <Card>Basil</Card>
-    <Card>Olive oil</Card>
-    <Card>Kosher Salt</Card>
-    <Card>Garlic</Card>
-    <Card>Pine nuts</Card>
-    <Card>Parmigiano Reggiano</Card>
-</CardList>
+import { CardList } from "@blueprintjs/core";
 ```
 
-@## Combining with Section
+@## Usage
 
-__CardList__ may be used as content for the [__Section__](#core/components/section) component (inside a nested
-__SectionCard__). This allows support for features like a title & description above the list.
+Use **CardList** to group multiple cards together in a vertical list.
 
-Set the same value for `<SectionCard padded>` and `<CardList bordered>` (either `true` or `false` for both) to get two
-different kinds of appearances.
+@reactCodeExample CardListBasicExample
 
-```tsx
-import { Card, CardList, Section, SectionCard } from "@blueprintjs/core";
-
-<Section title="Traditional pesto">
-    <SectionCard padded={false}>
-        <CardList bordered={false}>
-            <Card>Basil</Card>
-            <Card>Olive oil</Card>
-            {/* ... */}
-        </CardList>
-    </SectionCard>
-</Section>
-```
+@## Bordered
+
+To remove borders, set `bordered={false}`. This creates a seamless appearance
+when nesting **CardList** within other components.
+
+@reactCodeExample CardListBorderedExample
+
+@## Compact
+
+Enable the `compact` prop to reduce the padding inside each card in the list.
+
+@reactCodeExample CardListCompactExample
+
+@## Combining with section
+
+The **CardList** component can be embedded in a [**Section**](#core/components/section)
+component to add a title or description above the list.
+
+Set the same value for `<SectionCard padded>` and `<CardList bordered>`
+(either `true` or `false` for both) to get two different kinds of appearances.
+
+@reactCodeExample CardListSectionExample
+
+@## Interactive Playground
+
+@reactExample CardListPlaygroundExample
 
 @## Props interface
 

diff --git a/packages/docs-app/src/examples/core-examples/cardListExamples.tsx b/packages/docs-app/src/examples/core-examples/cardListExamples.tsx
@@ -0,0 +1,115 @@
+/* !
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ */
+
+import dedent from "dedent";
+import * as React from "react";
+
+import { Card, CardList, Section, SectionCard } from "@blueprintjs/core";
+import { CodeExample, type ExampleProps } from "@blueprintjs/docs-theme";
+
+export const CardListBasicExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <CardList>
+            <Card>Apples</Card>
+            <Card>Oranges</Card>
+            <Card>Bananas</Card>
+        </CardList>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <CardList>
+                <Card>Apples</Card>
+                <Card>Oranges</Card>
+                <Card>Bananas</Card>
+            </CardList>
+        </CodeExample>
+    );
+};
+
+export const CardListBorderedExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <CardList bordered={true}>
+            <Card>Bread</Card>
+            <Card>Cheese</Card>
+            <Card>Butter</Card>
+        </CardList>
+        <CardList bordered={false}>
+            <Card>Honey</Card>
+            <Card>Jam</Card>
+            <Card>Peanut Butter</Card>
+        </CardList>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <CardList bordered={true}>
+                <Card>Bread</Card>
+                <Card>Cheese</Card>
+                <Card>Butter</Card>
+            </CardList>
+            <CardList bordered={false}>
+                <Card>Honey</Card>
+                <Card>Jam</Card>
+                <Card>Peanut Butter</Card>
+            </CardList>
+        </CodeExample>
+    );
+};
+
+export const CardListCompactExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <CardList compact={false}>
+            <Card>Spaghetti</Card>
+            <Card>Lasagna</Card>
+            <Card>Ravioli</Card>
+        </CardList>
+        <CardList compact={true}>
+            <Card>Penne</Card>
+            <Card>Fettuccine</Card>
+            <Card>Rigatoni</Card>
+        </CardList>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <CardList compact={false}>
+                <Card>Spaghetti</Card>
+                <Card>Lasagna</Card>
+                <Card>Ravioli</Card>
+            </CardList>
+            <CardList compact={true}>
+                <Card>Penne</Card>
+                <Card>Fettuccine</Card>
+                <Card>Rigatoni</Card>
+            </CardList>
+        </CodeExample>
+    );
+};
+
+export const CardListSectionExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <Section title="Fresh Ingredients">
+            <SectionCard padded={false}>
+                <CardList bordered={false}>
+                    <Card>Tomatoes</Card>
+                    <Card>Garlic</Card>
+                    <Card>Olive Oil</Card>
+                    <Card>Basil</Card>
+                    <Card>Parmesan</Card>
+                    <Card>Pine Nuts</Card>
+                </CardList>
+            </SectionCard>
+        </Section>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <Section title="Fresh Ingredients">
+                <SectionCard padded={false}>
+                    <CardList bordered={false}>
+                        <Card>Tomatoes</Card>
+                        <Card>Garlic</Card>
+                        <Card>Olive Oil</Card>
+                        <Card>Basil</Card>
+                        <Card>Parmesan</Card>
+                        <Card>Pine Nuts</Card>
+                    </CardList>
+                </SectionCard>
+            </Section>
+        </CodeExample>
+    );
+};
diff --git a/...xamples/core-examples/cardListExample.tsx → ...re-examples/cardListPlaygroundExample.tsx b/...xamples/core-examples/cardListExample.tsx → ...re-examples/cardListPlaygroundExample.tsx
@@ -25,7 +25,7 @@ import { PropCodeTooltip } from "../../common/propCodeTooltip";
 
 const ingredients = ["Basil", "Olive oil", "Kosher salt", "Garlic", "Pine nuts", "Parmigiano Reggiano"];
 
-export const CardListExample: React.FC<ExampleProps> = props => {
+export const CardListPlaygroundExample: React.FC<ExampleProps> = props => {
     const [bordered, setBordered] = React.useState(true);
     const [compact, setCompact] = React.useState(false);
     const [interactive, setInteractive] = React.useState(true);

diff --git a/packages/docs-app/src/examples/core-examples/index.ts b/packages/docs-app/src/examples/core-examples/index.ts
@@ -25,7 +25,8 @@ export * from "./buttonPlaygroundExample";
 export * from "./calloutExamples";
 export * from "./calloutPlaygroundExample";
 export * from "./cardExamples";
-export * from "./cardListExample";
+export * from "./cardListExamples";
+export * from "./cardListPlaygroundExample";
 export * from "./cardPlaygroundExample";
 export { CheckboxCardExample } from "./checkboxCardExample";
 export * from "./checkboxExample";

diff --git a/packages/docs-app/src/styles/_examples.scss b/packages/docs-app/src/styles/_examples.scss
@@ -182,7 +182,41 @@
   }
 }
 
-#{example("CardList")} {
+#{example("CardListBasic")} {
+  .#{$ns}-card-list {
+    max-width: 300px;
+  }
+}
+
+#{example("CardListBordered")},
+#{example("CardListCompact")} {
+  .docs-code-example {
+    align-items: flex-start;
+    gap: $pt-grid-size * 2;
+  }
+
+  .#{$ns}-card-list {
+    max-width: 200px;
+  }
+}
+
+#{example("CardListSection")} {
+  .#{$ns}-card {
+    max-width: 400px;
+  }
+
+  .#{$ns}-section-card {
+    height: 152px;
+    overflow-y: auto;
+
+    .#{$ns}-dark & {
+      // need a bit of margin to account for inset box shadow
+      margin-bottom: 1px;
+    }
+  }
+}
+
+#{example("CardListPlayground")} {
   .docs-example > div {
     flex-grow: 1;
   }