Skip to content

Commit b95a86d

Browse files
ggdouglasggdouglas
authored
[docs] Rewrite CardList docs (#7112)
1 parent d09e8c9 commit b95a86d

File tree

5 files changed

+187
-37
lines changed

5 files changed

+187
-37
lines changed

‎packages/core/src/components/card-list/card-list.md‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -4,48 +4,48 @@ tag: new
44

55
@# Card List
66

7-
__CardList__ is a lightweight wrapper around the [__Card__](#core/components/card) component. It can be used to
8-
visually group together cards in a list without any excess visual weight around or between them. Long lists may
9-
be styled with CSS to scroll vertically.
7+
**CardList** is a lightweight wrapper around the [**Card**](#core/components/card) component.
8+
It groups cards visually into a list without adding extra visual weight or spacing between them.
9+
Long lists can be styled with CSS for vertical scrolling.
1010

11-
@reactExample CardListExample
12-
13-
@## Usage
11+
@## Import
1412

1513
```tsx
16-
import { Card, CardList } from "@blueprintjs/core";
17-
18-
<CardList>
19-
<Card>Basil</Card>
20-
<Card>Olive oil</Card>
21-
<Card>Kosher Salt</Card>
22-
<Card>Garlic</Card>
23-
<Card>Pine nuts</Card>
24-
<Card>Parmigiano Reggiano</Card>
25-
</CardList>
14+
import { CardList } from "@blueprintjs/core";
2615
```
2716

28-
@## Combining with Section
17+
@## Usage
2918

30-
__CardList__ may be used as content for the [__Section__](#core/components/section) component (inside a nested
31-
__SectionCard__). This allows support for features like a title & description above the list.
19+
Use **CardList** to group multiple cards together in a vertical list.
3220

33-
Set the same value for `<SectionCard padded>` and `<CardList bordered>` (either `true` or `false` for both) to get two
34-
different kinds of appearances.
21+
@reactCodeExample CardListBasicExample
3522

36-
```tsx
37-
import { Card, CardList, Section, SectionCard } from "@blueprintjs/core";
38-
39-
<Section title="Traditional pesto">
40-
<SectionCard padded={false}>
41-
<CardList bordered={false}>
42-
<Card>Basil</Card>
43-
<Card>Olive oil</Card>
44-
{/* ... */}
45-
</CardList>
46-
</SectionCard>
47-
</Section>
48-
```
23+
@## Bordered
24+
25+
To remove borders, set `bordered={false}`. This creates a seamless appearance
26+
when nesting **CardList** within other components.
27+
28+
@reactCodeExample CardListBorderedExample
29+
30+
@## Compact
31+
32+
Enable the `compact` prop to reduce the padding inside each card in the list.
33+
34+
@reactCodeExample CardListCompactExample
35+
36+
@## Combining with section
37+
38+
The **CardList** component can be embedded in a [**Section**](#core/components/section)
39+
component to add a title or description above the list.
40+
41+
Set the same value for `<SectionCard padded>` and `<CardList bordered>`
42+
(either `true` or `false` for both) to get two different kinds of appearances.
43+
44+
@reactCodeExample CardListSectionExample
45+
46+
@## Interactive Playground
47+
48+
@reactExample CardListPlaygroundExample
4949

5050
@## Props interface
5151

‎packages/docs-app/src/examples/core-examples/cardListExamples.tsx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/* !
2+
* (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
3+
*/
4+
5+
import dedent from "dedent";
6+
import * as React from "react";
7+
8+
import { Card, CardList, Section, SectionCard } from "@blueprintjs/core";
9+
import { CodeExample, type ExampleProps } from "@blueprintjs/docs-theme";
10+
11+
export const CardListBasicExample: React.FC<ExampleProps> = props => {
12+
const code = dedent`
13+
<CardList>
14+
<Card>Apples</Card>
15+
<Card>Oranges</Card>
16+
<Card>Bananas</Card>
17+
</CardList>`;
18+
return (
19+
<CodeExample code={code} {...props}>
20+
<CardList>
21+
<Card>Apples</Card>
22+
<Card>Oranges</Card>
23+
<Card>Bananas</Card>
24+
</CardList>
25+
</CodeExample>
26+
);
27+
};
28+
29+
export const CardListBorderedExample: React.FC<ExampleProps> = props => {
30+
const code = dedent`
31+
<CardList bordered={true}>
32+
<Card>Bread</Card>
33+
<Card>Cheese</Card>
34+
<Card>Butter</Card>
35+
</CardList>
36+
<CardList bordered={false}>
37+
<Card>Honey</Card>
38+
<Card>Jam</Card>
39+
<Card>Peanut Butter</Card>
40+
</CardList>`;
41+
return (
42+
<CodeExample code={code} {...props}>
43+
<CardList bordered={true}>
44+
<Card>Bread</Card>
45+
<Card>Cheese</Card>
46+
<Card>Butter</Card>
47+
</CardList>
48+
<CardList bordered={false}>
49+
<Card>Honey</Card>
50+
<Card>Jam</Card>
51+
<Card>Peanut Butter</Card>
52+
</CardList>
53+
</CodeExample>
54+
);
55+
};
56+
57+
export const CardListCompactExample: React.FC<ExampleProps> = props => {
58+
const code = dedent`
59+
<CardList compact={false}>
60+
<Card>Spaghetti</Card>
61+
<Card>Lasagna</Card>
62+
<Card>Ravioli</Card>
63+
</CardList>
64+
<CardList compact={true}>
65+
<Card>Penne</Card>
66+
<Card>Fettuccine</Card>
67+
<Card>Rigatoni</Card>
68+
</CardList>`;
69+
return (
70+
<CodeExample code={code} {...props}>
71+
<CardList compact={false}>
72+
<Card>Spaghetti</Card>
73+
<Card>Lasagna</Card>
74+
<Card>Ravioli</Card>
75+
</CardList>
76+
<CardList compact={true}>
77+
<Card>Penne</Card>
78+
<Card>Fettuccine</Card>
79+
<Card>Rigatoni</Card>
80+
</CardList>
81+
</CodeExample>
82+
);
83+
};
84+
85+
export const CardListSectionExample: React.FC<ExampleProps> = props => {
86+
const code = dedent`
87+
<Section title="Fresh Ingredients">
88+
<SectionCard padded={false}>
89+
<CardList bordered={false}>
90+
<Card>Tomatoes</Card>
91+
<Card>Garlic</Card>
92+
<Card>Olive Oil</Card>
93+
<Card>Basil</Card>
94+
<Card>Parmesan</Card>
95+
<Card>Pine Nuts</Card>
96+
</CardList>
97+
</SectionCard>
98+
</Section>`;
99+
return (
100+
<CodeExample code={code} {...props}>
101+
<Section title="Fresh Ingredients">
102+
<SectionCard padded={false}>
103+
<CardList bordered={false}>
104+
<Card>Tomatoes</Card>
105+
<Card>Garlic</Card>
106+
<Card>Olive Oil</Card>
107+
<Card>Basil</Card>
108+
<Card>Parmesan</Card>
109+
<Card>Pine Nuts</Card>
110+
</CardList>
111+
</SectionCard>
112+
</Section>
113+
</CodeExample>
114+
);
115+
};

‎packages/docs-app/src/examples/core-examples/cardListExample.tsx‎ renamed to ‎packages/docs-app/src/examples/core-examples/cardListPlaygroundExample.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ import { PropCodeTooltip } from "../../common/propCodeTooltip";
2525

2626
const ingredients = ["Basil", "Olive oil", "Kosher salt", "Garlic", "Pine nuts", "Parmigiano Reggiano"];
2727

28-
export const CardListExample: React.FC<ExampleProps> = props => {
28+
export const CardListPlaygroundExample: React.FC<ExampleProps> = props => {
2929
const [bordered, setBordered] = React.useState(true);
3030
const [compact, setCompact] = React.useState(false);
3131
const [interactive, setInteractive] = React.useState(true);

‎packages/docs-app/src/examples/core-examples/index.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ export * from "./buttonPlaygroundExample";
2525
export * from "./calloutExamples";
2626
export * from "./calloutPlaygroundExample";
2727
export * from "./cardExamples";
28-
export * from "./cardListExample";
28+
export * from "./cardListExamples";
29+
export * from "./cardListPlaygroundExample";
2930
export * from "./cardPlaygroundExample";
3031
export { CheckboxCardExample } from "./checkboxCardExample";
3132
export * from "./checkboxExample";

‎packages/docs-app/src/styles/_examples.scss‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,41 @@
182182
}
183183
}
184184

185-
#{example("CardList")} {
185+
#{example("CardListBasic")} {
186+
.#{$ns}-card-list {
187+
max-width: 300px;
188+
}
189+
}
190+
191+
#{example("CardListBordered")},
192+
#{example("CardListCompact")} {
193+
.docs-code-example {
194+
align-items: flex-start;
195+
gap: $pt-grid-size * 2;
196+
}
197+
198+
.#{$ns}-card-list {
199+
max-width: 200px;
200+
}
201+
}
202+
203+
#{example("CardListSection")} {
204+
.#{$ns}-card {
205+
max-width: 400px;
206+
}
207+
208+
.#{$ns}-section-card {
209+
height: 152px;
210+
overflow-y: auto;
211+
212+
.#{$ns}-dark & {
213+
// need a bit of margin to account for inset box shadow
214+
margin-bottom: 1px;
215+
}
216+
}
217+
}
218+
219+
#{example("CardListPlayground")} {
186220
.docs-example > div {
187221
flex-grow: 1;
188222
}

0 commit comments

Comments
 (0)