From b95a86d7467183af9757236f6d7d30696f788fb5 Mon Sep 17 00:00:00 2001 From: Greg Douglas Date: Tue, 10 Dec 2024 12:21:24 -0500 Subject: [PATCH] [docs] Rewrite CardList docs (#7112) --- .../src/components/card-list/card-list.md | 68 +++++------ .../core-examples/cardListExamples.tsx | 115 ++++++++++++++++++ ...mple.tsx => cardListPlaygroundExample.tsx} | 2 +- .../src/examples/core-examples/index.ts | 3 +- packages/docs-app/src/styles/_examples.scss | 36 +++++- 5 files changed, 187 insertions(+), 37 deletions(-) create mode 100644 packages/docs-app/src/examples/core-examples/cardListExamples.tsx rename packages/docs-app/src/examples/core-examples/{cardListExample.tsx => cardListPlaygroundExample.tsx} (98%) diff --git a/packages/core/src/components/card-list/card-list.md b/packages/core/src/components/card-list/card-list.md index 94ea125c36..e88889c423 100644 --- 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"; - - - Basil - Olive oil - Kosher Salt - Garlic - Pine nuts - Parmigiano Reggiano - +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 `` and `` (either `true` or `false` for both) to get two -different kinds of appearances. +@reactCodeExample CardListBasicExample -```tsx -import { Card, CardList, Section, SectionCard } from "@blueprintjs/core"; - -
- - - Basil - Olive oil - {/* ... */} - - -
-``` +@## 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 `` and `` +(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 new file mode 100644 index 0000000000..1e0faef8f6 --- /dev/null +++ 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 = props => { + const code = dedent` + + Apples + Oranges + Bananas + `; + return ( + + + Apples + Oranges + Bananas + + + ); +}; + +export const CardListBorderedExample: React.FC = props => { + const code = dedent` + + Bread + Cheese + Butter + + + Honey + Jam + Peanut Butter + `; + return ( + + + Bread + Cheese + Butter + + + Honey + Jam + Peanut Butter + + + ); +}; + +export const CardListCompactExample: React.FC = props => { + const code = dedent` + + Spaghetti + Lasagna + Ravioli + + + Penne + Fettuccine + Rigatoni + `; + return ( + + + Spaghetti + Lasagna + Ravioli + + + Penne + Fettuccine + Rigatoni + + + ); +}; + +export const CardListSectionExample: React.FC = props => { + const code = dedent` +
+ + + Tomatoes + Garlic + Olive Oil + Basil + Parmesan + Pine Nuts + + +
`; + return ( + +
+ + + Tomatoes + Garlic + Olive Oil + Basil + Parmesan + Pine Nuts + + +
+ + ); +}; diff --git a/packages/docs-app/src/examples/core-examples/cardListExample.tsx b/packages/docs-app/src/examples/core-examples/cardListPlaygroundExample.tsx similarity index 98% rename from packages/docs-app/src/examples/core-examples/cardListExample.tsx rename to packages/docs-app/src/examples/core-examples/cardListPlaygroundExample.tsx index 73336e4b81..b19ef0d328 100644 --- a/packages/docs-app/src/examples/core-examples/cardListExample.tsx +++ b/packages/docs-app/src/examples/core-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 = props => { +export const CardListPlaygroundExample: React.FC = 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 index e84a4246ef..39805eb4f7 100644 --- 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 index d217266951..b5183665c5 100644 --- 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; }