Skip to content

Commit c3cf203

Browse files
ggdouglasggdouglas
authored
[docs] Rewrite Card docs (#7111)
1 parent 7cfe182 commit c3cf203

File tree

10 files changed

+167
-34
lines changed

10 files changed

+167
-34
lines changed

‎packages/core/src/components/breadcrumbs/breadcrumbs.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
**Breadcrumbs** represent the path to the current resource within an application's hierarchical structure.
44

5-
@## Usage
5+
@## Import
66

77
```ts
88
import { Breadcrumbs } from "@blueprintjs/core";
99
```
1010

11-
@## Basic breadcrumbs
11+
@## Usage
1212

1313
The **Breadcrumbs** component accepts an `items` array of
1414
[breadcrumb props](#core/components/breadcrumbs.breadcrumb) and renders them as an ordered list.

‎packages/core/src/components/button/button-group.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@
33
The **ButtonGroup** component arranges related buttons in a horizontal row or
44
vertical stack, providing alignment and consistent spacing for a layout of related actions.
55

6-
@## Usage
6+
@## Import
77

88
```ts
99
import { ButtonGroup } from "@blueprintjs/core";
1010
```
1111

12-
@## Basic button group
12+
@## Usage
1313

1414
Wrap buttons in a **ButtonGroup** to arrange them together horizontally.
1515

‎packages/core/src/components/button/buttons.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
A **Button** is a clickable element used to trigger actions or events. Buttons allow users to perform an action or navigate to another page with a single click. They are typically found in forms, toolbars, dialogs, and other areas where users need to make choices or initiate actions.
44

5-
@## Usage
5+
@## Import
66

77
```tsx
88
import { Button } from "@blueprintjs/core";
99
```
1010

11-
@## Basic button
11+
@## Usage
1212

1313
The `text` prop defines the label displayed on the button. Alternatively, content can be provided as children, allowing for more flexibility, such as including multiple elements or custom markup.
1414

‎packages/core/src/components/callout/callout.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@
33
**Callouts** visually highlight important content for the user. They may contain
44
a title, an icon and content. Each intent has a default icon associated with it.
55

6-
@## Usage
6+
@## Import
77

88
```tsx
99
import { Callout } from "@blueprintjs/core";
1010
```
1111

12-
@## Basic callout
12+
@## Usage
1313

1414
A **Callout** highlights important content with an optional title and body text.
1515

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

Lines changed: 37 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,50 @@
11
@# Card
22

3-
A **Card** is a bounded unit of UI content with a solid background color.
3+
A **Card** is a bounded container for grouping related content with a solid
4+
background color. It offers customizable padding, interactivity, and elevation.
45

5-
@reactExample CardExample
6-
7-
@## Usage
6+
@## Import
87

98
```tsx
10-
import { Button, Card, Elevation } from "@blueprintjs/core";
11-
12-
<Card interactive={true} elevation={Elevation.TWO}>
13-
<h5>
14-
<a href="#">Card heading</a>
15-
</h5>
16-
<p>Card content</p>
17-
<Button>Submit</Button>
18-
</Card>;
9+
import { Card } from "@blueprintjs/core";
1910
```
2011

12+
@## Usage
13+
14+
A **Card** provides a structured container for text, actions, or other content.
15+
Use it to present a cohesive unit of information.
16+
17+
@reactCodeExample CardBasicExample
18+
19+
@## Interactive
20+
21+
The `interactive` prop makes a **Card** appear responsive to hover and click events.
22+
Combine it with an `onClick` handler to perform actions when the card is clicked,
23+
such as navigation or selection.
24+
25+
Additionally, the `selected` prop can be used to indicate a selection state.
26+
27+
@reactCodeExample CardInteractiveExample
28+
29+
@## Compact
30+
31+
Enable the `compact` prop to reduce the padding of the **Card**, resulting in a more condensed appearance.
32+
33+
@reactCodeExample CardCompactExample
34+
2135
@## Elevation
2236

23-
Apply an `elevation` value to a card to apply a drop shadow that simulates height in the UI.
24-
Five elevations are supported, from 0 to 4.
37+
The `elevation` prop controls the shadow depth of the **Card**, creating a visual
38+
hierarchy. Five elevations are supported, from 0 to 4. Higher elevation values
39+
make the **Card** appear more prominent.
40+
41+
> Note that the `Classes.ELEVATION_*` classes can be used on any element (not just a `Card`) to apply the box shadow.
42+
43+
@reactCodeExample CardElevationExample
44+
45+
@## Interactive Playground
2546

26-
Note that the `Classes.ELEVATION_*` classes can be used on any element (not just a `Card`) to apply the drop shadow.
47+
@reactExample CardPlaygroundExample
2748

2849
@## Props interface
2950

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ import { CodeExample, type ExampleProps } from "@blueprintjs/docs-theme";
1111
export const BreadcrumbsBasicExample: React.FC<ExampleProps> = props => {
1212
const code = dedent`
1313
<Breadcrumbs
14-
items={[
15-
{ text: "Blueprint" },
16-
{ text: "Docs" },
17-
{ text: "Components" },
18-
{ text: "Breadcrumbs" },
19-
]}
14+
items={[
15+
{ text: "Blueprint" },
16+
{ text: "Docs" },
17+
{ text: "Components" },
18+
{ text: "Breadcrumbs" },
19+
]}
2020
/>`;
2121
return (
2222
<CodeExample code={code} {...props}>

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
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 { Button, Card, Elevation, H3 } from "@blueprintjs/core";
9+
import { CodeExample, type ExampleProps } from "@blueprintjs/docs-theme";
10+
11+
export const CardBasicExample: React.FC<ExampleProps> = props => {
12+
const code = dedent`
13+
<Card>
14+
<H3>Adventure Awaits</H3>
15+
<p>Embark on an epic journey across uncharted lands. This card outlines your mission.</p>
16+
<Button intent="primary">Start Journey</Button>
17+
</Card>`;
18+
return (
19+
<CodeExample code={code} {...props}>
20+
<Card>
21+
<H3>Adventure Awaits</H3>
22+
<p>Embark on an epic journey across uncharted lands. This card outlines your mission.</p>
23+
<Button intent="primary">Start Journey</Button>
24+
</Card>
25+
</CodeExample>
26+
);
27+
};
28+
29+
export const CardInteractiveExample: React.FC<ExampleProps> = props => {
30+
const code = dedent`
31+
<Card interactive={true} onClick={...}>
32+
This card is interactive. Hover and click it.
33+
</Card>
34+
<Card interactive={true} selected={true}>
35+
This card is selected.
36+
</Card>`;
37+
return (
38+
<CodeExample code={code} {...props}>
39+
{/* eslint-disable-next-line no-console */}
40+
<Card interactive={true} onClick={() => console.log("clicked card")}>
41+
This card is interactive. Hover and click it.
42+
</Card>
43+
<Card interactive={true} selected={true}>
44+
This card is selected.
45+
</Card>
46+
</CodeExample>
47+
);
48+
};
49+
50+
export const CardCompactExample: React.FC<ExampleProps> = props => {
51+
const code = dedent`
52+
<Card>This card has default padding.</Card>
53+
<Card compact={true}>This card is more compact.</Card>`;
54+
return (
55+
<CodeExample code={code} {...props}>
56+
<Card>This card has default padding.</Card>
57+
<Card compact={true}>This card is more compact.</Card>
58+
</CodeExample>
59+
);
60+
};
61+
62+
export const CardElevationExample: React.FC<ExampleProps> = props => {
63+
const code = dedent`
64+
<Card elevation={Elevation.ZERO}>0</Card>
65+
<Card elevation={Elevation.ONE}>1</Card>
66+
<Card elevation={Elevation.TWO}>2</Card>
67+
<Card elevation={Elevation.THREE}>3</Card>
68+
<Card elevation={Elevation.FOUR}>4</Card>`;
69+
return (
70+
<CodeExample code={code} {...props}>
71+
<Card elevation={Elevation.ZERO}>0</Card>
72+
<Card elevation={Elevation.ONE}>1</Card>
73+
<Card elevation={Elevation.TWO}>2</Card>
74+
<Card elevation={Elevation.THREE}>3</Card>
75+
<Card elevation={Elevation.FOUR}>4</Card>
76+
</CodeExample>
77+
);
78+
};

‎packages/docs-app/src/examples/core-examples/cardExample.tsx‎ renamed to ‎packages/docs-app/src/examples/core-examples/cardPlaygroundExample.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ import { Example, type ExampleProps, handleBooleanChange } from "@blueprintjs/do
2121

2222
const MAX_ELEVATION = 4;
2323

24-
export const CardExample: React.FC<ExampleProps> = props => {
24+
export const CardPlaygroundExample: React.FC<ExampleProps> = props => {
2525
const [compact, setCompact] = React.useState(false);
2626
const [elevation, setElevation] = React.useState<Elevation>(Elevation.ZERO);
2727
const [interactive, setInteractive] = React.useState(false);

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,14 @@ export * from "./buttonGroupExamples";
2222
export * from "./buttonGroupPlaygroundExample";
2323
export * from "./buttonGroupPopoverExample";
2424
export * from "./buttonPlaygroundExample";
25-
export * from "./calloutPlaygroundExample";
2625
export * from "./calloutExamples";
26+
export * from "./calloutPlaygroundExample";
27+
export * from "./cardExamples";
28+
export * from "./cardListExample";
29+
export * from "./cardPlaygroundExample";
2730
export { CheckboxCardExample } from "./checkboxCardExample";
2831
export * from "./checkboxExample";
2932
export * from "./collapseExample";
30-
export * from "./cardExample";
31-
export * from "./cardListExample";
3233
export { CompoundTagExample } from "./compoundTagExample";
3334
export { ContextMenuExample } from "./contextMenuExample";
3435
export { ContextMenuPopoverExample } from "./contextMenuPopoverExample";

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,39 @@
149149
}
150150
}
151151

152+
#{example("CardInteractive")},
153+
#{example("CardCompact")} {
154+
.docs-code-example {
155+
flex-direction: column;
156+
gap: $pt-grid-size;
157+
}
158+
159+
.#{$ns}-card {
160+
max-width: 400px;
161+
text-align: center;
162+
width: 100%;
163+
}
164+
}
165+
166+
#{example("CardElevation")} {
167+
.docs-code-example {
168+
gap: $pt-grid-size * 4;
169+
170+
// lighten the example background in dark mode to make elevation shadows visible
171+
.#{$ns}-dark & {
172+
background-color: $dark-gray3;
173+
}
174+
}
175+
176+
.#{$ns}-card {
177+
align-items: center;
178+
display: flex;
179+
height: 60px;
180+
justify-content: center;
181+
width: 60px;
182+
}
183+
}
184+
152185
#{example("CardList")} {
153186
.docs-example > div {
154187
flex-grow: 1;

0 commit comments

Comments
 (0)