funkwhale/front/ui-docs/components/ui/card.md

<script setup lang="ts">
  import Card from '~/components/card/Card.vue'
  import Spacer from '~/components/layout/Spacer.vue'
  import { useRouter } from 'vue-router'

  const alert = (message: string) => window.alert(message)
  const router = useRouter()
</script>

# Card

Funkwhale cards are used to contain textual information, links, and interactive buttons. You can use these to create visually pleasing links to content or to present information.

::: details Parameters

#### Props

```ts
interface Props extends Partial<RouterLinkProps> {
  title: string;
  category?: true | "h1" | "h2" | "h3" | "h4" | "h5";
  color?: Pastel;
  image?: string | { src: string; style?: "withPadding" };
  tags?: string[];
}
```

You have to set a title for the card by passing a `title` prop.

#### Style

- Set `--width` on the element to override the default Card width.

:::

```vue-html
<Card title="For music lovers">
  Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card>
```

<div class="preview">
<Card title="For music lovers">
  Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card></div>

## Card as a Link

::: warning

TODO: Test if it works. Set up a mock router in vitest.

:::

Add a `:to` prop, either containing an external link (`"https://..."`) or a Vue Router destination:

```ts
:to="{name: 'library.albums.detail', params: {id: album.id}}"
```

<div class="preview">
<Card
title="Frequently Asked Questions"
@click="alert('A quick answer!')"
>
Got a question about Funkwhale? Get a quick answer!
</Card></div>

## Card as a Category header

Category cards are basic cards that contain only a title. To create a category card, pass a `category` prop.

```vue-html{1}
<Card category
  title="Example Translations"
/>
```

<div class="preview">
  <Card category
  title="Example Translations"
  />
</div>

## Add an Image

Pass an image source to the `image` prop or set `image.src` and `image.style`.

```vue-html{4,11-12}
<Card
  style="--width:208px"
  title="For music lovers"
  image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb">
</Card>


<Card
  style="--width:208px"
  title="For music lovers"
  :image="{ src:'https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb',
            style:'withPadding' }">
</Card>
```

<fw-layout flex>
<div class="preview">
<Card
  style="--width:208px"
title="For music lovers"
  image="https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb" />
</div>

<div class="preview">
<Card
  style="--width:208px"
title="For music lovers"
:image="{ src:'https://images.unsplash.com/photo-1524650359799-842906ca1c06?ixlib=rb-1.2.1&dl=te-nguyen-Wt7XT1R6sjU-unsplash.jpg&w=640&q=80&fm=jpg&crop=entropy&cs=tinysrgb',
          style:'withPadding' }" />
</div>
</fw-layout>

## Add an Alert

```vue-html{2-4}
<Card title="Your Collection">
  <template #alert>
    Please annotate all items with the required metadata.
  </template>
</Card>
```

<div class="preview">
<Card title="Your Collection">
  <template #alert>Please annotate all items with the required metadata.</template>
</Card>
</div>

## Add a Footer

Items in this region are secondary and will be displayed smaller than the main content.

```vue-html{3-9}
<Card title="My items">
  <template #alert> There are no items in this list </template>
  <template #footer>
    <fw-button variant="outline" icon="bi-upload" @click="alert('Uploaded. Press OK!')">
      Upload
    </fw-button>
    <Spacer style="flex-grow: 1" />
    <fw-options-button />
  </template>
</Card>
```

<div class="preview">
<Card title="My items">

<template #alert>There are no items in this list
</template>

<template #footer>
<fw-button variant="outline" icon="bi-upload" @click="alert('Uploaded. Press OK!')">Upload</fw-button>
<Spacer style="flex-grow: 1" />
<fw-options-button />
</template>

</Card>
</div>

## Add an Action

Large Buttons or links at the bottom edge of the card serve as Call-to-Actions (CTA).

```vue-html{3-6}
<Card title="Join an existing pod">
  The easiest way to get started with Funkwhale is to register an account on a public pod.
  <template #action>
    <fw-button @click="alert('Open the pod picker')">Action!
    </fw-button>
  </template>
</Card>
```

<div class="preview">
  <Card title="Join an existing pod">
    The easiest way to get started with Funkwhale is to register an account on a public pod.
    <template #action>
      <fw-button @click="alert('Open the pod picker')">Action!
      </fw-button>
    </template>
  </Card>
</div>

If there are multiple actions, they will be presented in a row:

```vue-html{4,7}
<Card title="Delete this pod?">
  You cannot undo this action.
  <template #action>
    <fw-button style="justify-content: flex-start;" icon="bi-chevron-left" color="secondary" variant="ghost">
      Back
    </fw-button>
    <fw-button style="flex-grow:0;" color="destructive" @click="alert('Deleted')">
      Delete
    </fw-button>
  </template>
</Card>
```

<div class="preview">
  <Card title="Delete this pod?">
    You cannot undo this action.
    <template #action>
      <fw-button style="width:50%; justify-content: flex-start;" icon="bi-chevron-left" color="secondary" variant="ghost">
        Back
      </fw-button>
      <fw-button style="width:50%" color="destructive" @click="alert('Deleted')">
        Delete
      </fw-button>
    </template>
  </Card>
</div>

## Add Tags

You can include tags on a card by adding a list of `tags`. These are rendered as [pills](./pill.md).

```vue-html{3}
<Card
  title="For music lovers"
  :tags="['rock', 'folk', 'punk']"
>
  Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card>
```

<div class="preview">
<Card
title="For music lovers"
:tags="['rock', 'folk', 'punk']">
Access your personal music collection from anywhere. Funkwhale gives you access to publication and sharing tools that you can use to promote your content across the web.
</Card></div>