From 8b45ad181c4f5bbdd3bea76d4f3b5c5c45b5c351 Mon Sep 17 00:00:00 2001 From: Sara Date: Fri, 18 Apr 2025 18:30:29 -0400 Subject: [PATCH] Update `sl-card` documentation --- docs/pages/components/card.md | 429 ++++++++++++++++++++++++++++------ 1 file changed, 353 insertions(+), 76 deletions(-) diff --git a/docs/pages/components/card.md b/docs/pages/components/card.md index 8a431f66..69482b2a 100644 --- a/docs/pages/components/card.md +++ b/docs/pages/components/card.md @@ -121,14 +121,20 @@ const App = () => ( ### Basic Card -Basic cards aren't very exciting, but they can display any content you want them to. +Basic cards aren't very exciting, but they can display any content you want them to. This is the standard container to use when displaying content on a standard page with a `gray-100` background. ```html:preview - - This is just a basic card. No image, no header, and no footer. Just your content. - +
+ + This is just a basic card. No image, no header, and no footer. Just your content. + +
``` ```pug:slim -sl-card.card-basic noShadow=true - | This is just a basic card with no shadow. +.page-basic + sl-card + div slot="header" Card with nested cards + .nested-cards + sl-card noShadow=true + | This is a basic card with no shadow, nested inside a standard card with shadow. + sl-card noShadow=true + | This is a basic card with no shadow, nested inside a standard card with shadow. + sl-card noShadow=true + | This is a basic card with no shadow, nested inside a standard card with shadow. css: - .card-basic { - max-width: 300px; + .page-basic { + @apply bg-gray-100 p-6; + } + .nested-cards { + @apply grid grid-cols-2 w-full gap-4; } ``` @@ -209,57 +251,204 @@ const App = () => ( ); ``` -### Card with Header +### Loading Card -Headers can be used to display titles, actions, and more. Other than padding and a bottom border, headers have no styling applied by default. +Use the `loading` property to indicate that a process related to a card is in progress. An overlay will cover the entire card and an `sl-spinner` component will be displayed on top of the overlay. ```html:preview - -
- Card header - -
- - This card has a header. You can put all sorts of things in it! - +
+ + This is a basic card in a loading state. + +
``` ```pug:slim -sl-card.card-header - div slot="header" - | Card header - sl-icon-button library="fa" name="fas-pencil" label="Edit settings" - | This card has a header. You can put all sorts of things in it! +.page-basic + sl-card.card-loading loading=true + | This is a basic card in a loading state. css: - .card-header { + .page-basic { + @apply bg-gray-100 p-6; + } + .card-loading { + @apply max-w-[300px]; + } +``` + +```jsx:react +import { SlCard } from '@teamshares/shoelace/dist/react'; + +const css = ` + .card-basic { max-width: 300px; } +`; - .card-header [slot=header] { - display: flex; - align-items: center; - justify-content: space-between; +const App = () => ( + <> + + This is a basic card in a loading state. + + + + +); +``` + +### Empty State Card + +Use the `emptyState` property to style the card for an empty state. This will make the card less prominent by setting the background color to transparent (showing the `gray-100` page behind it) and darken the border slightly. + +```html:preview +
+ + This is a basic card styled as an empty state container. +

+ Fill it with content using the Empty State View Component! + +
+ +``` + +```pug:slim +.page-basic + sl-card.card-empty emptyState=true + | This is a basic card styled as an empty state container. + br + br + | Fill it with content using the Empty State View Component! + +css: + .page-basic { + @apply bg-gray-100 p-6; + } + .card-empty { + @apply max-w-[300px]; + } +``` + +```jsx:react +import { SlCard } from '@teamshares/shoelace/dist/react'; + +const css = ` + .card-basic { + max-width: 300px; + } +`; + +const App = () => ( + <> + + This is a basic card in a loading state. + + + + +); +``` + +### Card with Header + +Use `slot="header"` to display header content in the card. Other than padding and a bottom border, headers have no styling applied by default. + +To optionally apply a flex/space-between layout to a header with a title and one or more button actions (or other content to display on the right), use the `actionHeader` property on `sl-card`. + +```html:preview +
+ +
+
Card title
+
Description
+
+ This card has a header with no additional styling applied by default. + + +
+
Card title
+
+ + + + + + +
+
+ This card is using the actionHeader property, which applies a flex/space-between layout to the header. +

+ To display more than one action button, wrap the buttons in a container. + +
+ +``` + +```pug:slim +.page-basic + sl-card.card-header + div slot="header" + .ts-heading-7 Card title + .ts-body-2 Description + | This card has a header with no additional styling applied by default. + sl-card.card-header actionHeader=true + div slot="header" + .ts-heading-7 Card title + .header-actions + sl-tooltip content="Edit" + sl-icon-button library="fa" name="pencil" + sl-tooltip content="Delete" + sl-icon-button library="fa" name="trash" + | This card is using the + code actionHeader + | property, which applies a + code flex/space-between + | layout to the header. + br + br + | To display more than one action button, wrap the buttons in a container. + +css: + .page-basic { + @apply bg-gray-100 p-6; } - .card-header sl-icon-button { - font-size: var(--sl-font-size-medium); + .card-header { + @apply my-2 w-full; + } + + .header-actions * { + @apply ms-2; } ``` @@ -300,55 +489,143 @@ const App = () => ( ### Card with Footer -Footers can be used to display actions, summaries, or other relevant content. Similar to the header, footers have no styling applied by default other than padding and a top border. +Use `slot="footer"` to display footer content in the card. Similar to the header, footers have no styling applied by default other than padding and a top border. + +To optionally apply a `flex/flex-end` layout to a footer with one or more buttons, use the `buttonFooter` property on `sl-card`. ```html:preview - - This card has a footer. You can put all sorts of things in it! - -
- Previous - Next -
- +
+ + This card has a footer with no additional styling applied by default. +
+ Use for links or whatever! +
+ + + This card is using the buttonFooter property, which applies a flex/flex-end layout and 8 px gapto footer elements. +
+ Default + Primary +
+ +
``` ```pug:slim -sl-card.card-footer - | This card has a footer. You can put all sorts of things in it! - div slot="footer" - sl-rating - sl-button variant="primary" Preview - +.page-basic + sl-card.card-footer + | This card has a footer with no additional styling applied by default. + div slot="footer" + a href="#" class="ts-body-2 ts-text-link" Use for links or whatever! + sl-card.card-footer buttonFooter=true + | Thi s card is using the + code buttonFooter + | property, which applies a + code flex/flex-end + | layout and + code 8 px gap + | to footer elements. + div slot="footer" + sl-button variant="default" Default + sl-button variant="primary" Primary css: + .page-basic { + @apply bg-gray-100 p-6; + } + .card-footer { + @apply my-2 w-full; + } +``` + +```jsx:react +import SlButton from '@teamshares/shoelace/dist/react/button'; +import SlCard from '@teamshares/shoelace/dist/react/card'; +import SlRating from '@teamshares/shoelace/dist/react/rating'; + +const css = ` .card-footer { max-width: 300px; } - .card-footer [slot=footer] { + .card-footer [slot="footer"] { display: flex; justify-content: space-between; align-items: center; } .card-footer [slot='footer'] > * { - margin-inline-start: 0.5rem; + margin-inline-start: 0.5rem; + } +`; + +const App = () => ( + <> + + This card has a footer. You can put all sorts of things in it! +
+ + + Preview + +
+ + + + +); +``` + +### Compact Card + +Use the `compact` property to reduce spacing and remove the borders between the header, body, and footer. + +```html:preview +
+ +
+
Compact card header
+
+ This card is using the compact property, which reduces spacing and removes the borders between the header, body, and footer. +
+ Default + Primary +
+ +
+ + +``` + +```pug:slim +.page-basic + sl-card.card-compact compact=true buttonFooter=true + div slot="header + .ts-heading-8 Compact card header + | This card is using the + code compact + | property, which reduces spacing and removes the borders between the header, body, and footer. + div slot="footer" + sl-button variant="default" size="small" Default + sl-button variant="primary" size="small" Primary + +css: + .card-footer { + @apply w-[400px]; } ```