funkwhale/front/ui-docs/components/ui/layout/section.md

<script setup lang="ts">
import { computed, ref } from 'vue'

import { type Track, type User } from '~/types'

import Card from '~/components/ui/Card.vue'
import Layout from '~/components/ui/Layout.vue'
import Toggle from '~/components/ui/Toggle.vue'
import Spacer from '~/components/ui/Spacer.vue'
import Activity from '~/components/ui/Activity.vue'
import Section from '~/components/ui/Section.vue'

const alignLeft = ref(true)

const track: Track = {
  id: 0,
  fid: "",

  title: 'Some lovely track',
  description: {
    content_type: 'text/markdown',
    text: `**New:** Music for the eyes!`
  },
  cover: {
    uuid: "",
    urls: {
      original: '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',
      medium_square_crop: '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',
      large_square_crop: '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'
    }
  },
  tags: ["example"],
  uploads: [],
  downloads_count: 1927549377,
  artist_credit: [{
    artist: {
      id: 0,
      fid: "",

      name: "The Artist",
      description: {
        content_type: 'text/markdown',
        text: `I'm a musician based on the internet.

  Find all my music on [Funkwhale](https://funkwhale.audio)!`},
      tags: [],

      content_category: 'music',
      albums: [],
      tracks_count: 1,
      attributed_to: {
        id: 0,
        summary: "",
        preferred_username: "User12345",
        full_username: "User12345",
        is_local: false,
        domain: "myDomain.io"
      },
      is_local: false,
      is_playable: true
    },
    credit: "",
    joinphrase: " and ",
    index: 22
  }],
  disc_number: 7,

  listen_url: "https://funkwhale.audio",
  creation_date: "12345",
  attributed_to: {
    id: 0,
    summary: "",
    preferred_username: "User12345",
    full_username: "User12345",
    is_local: false,
    domain: "myDomain.io"
  },

  is_playable: true,
  is_local: false
}

const user: User = {
  id: 12,
  avatar: {
    uuid: "",
    urls: {
      original: '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',
      medium_square_crop: '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',
      large_square_crop: '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'
    }
  },
  email: "user12345@example.org",
  summary: { text: "Hi! I'm Example from The Internet.", content_type: "text" },
  username: "user12345",
  full_username: "user12345",
  instance_support_message_display_date: "?",
  funkwhale_support_message_display_date: "?",
  is_superuser: true,
  privacy_level: "everyone"
}
</script>

```ts
import Section from "~/components/ui/Section.vue"
```

# Layout section

Sections divide the page vertically. Choose an appropriate heading level for each section: `h1` or `h2` or `h3`.

```vue-html
<Section h3="My title" />
```

### Align the section to the page

```vue-html
<Section h3="My title" alignLeft />
```

### Make the section header align with the section contents

Do you want to align the header to no, tiny, small or medium items?

If all items stretch all columns (`style=grid-column: 1 / -1`), use `no-items`.

```vue-html
<Section medium-items />
```

### Provide an action

The link or button will be shown on the right side of the header.

```vue-html
<Layout stack gap-64>
  <Spacer />
  <Section h3="With a link" 
    :action="{ text:'My library', to:'/' }" />

  <Section h3="With a button" 
    :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />
</Layout>
```

<Spacer />
<Layout stack gap-64>
<Section h3="With a link" :action="{ text:'My library', to:'/' }" />
<Section h3="With a button" :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />
</Layout>

You can add props to the Link or Button, for example to make them `primary` or add an icon:

```vue-html{1}
<Section solid primary icon="bi-star"
    h3="Example" :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />
```

<Spacer :size="40"/>

<Section solid primary icon="bi-star"
    h3="Example" :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />

::: tip Gaps between consecutive sections

Place consecutive sections into a [Layout stack](../layout) width a size of 64px give them a regular vertical rhythm. Use different sizes for very small or very large headings.
You can add spacers with negative or positive size if you want to manually make a specific distance smaller or larger than the others.

```vue-html
<Layout stack gap-64>
  <Spacer />
  <Section h3="Section 1" />
  <Section h3="Section 2" />
</Layout>
```

<Layout stack gap-64>
  <Spacer no-size />
  <Section h3="Section 1" />
  <Section h3="Section 2" />
</Layout>

<Spacer />

:::

::: tip Let items cover the whole grid width

To prevent items from being put on a grid, add `style="grid-column: 1 / -1"` which means that they span "all existing columns".

:::

## Example

```vue-html
<Layout flex>
<Toggle v-model="alignLeft" label="Left-align the layout"/>
</Layout>

<Spacer />

<Layout stack gap-64>

<Section :alignLeft="alignLeft" small-items h3="Cards (small items)" :action="{ text:'more...', to:'/' }">
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
</Section>

<Section
    :alignLeft="alignLeft"
    medium-items
    h3="Activities (medium items)"
    :action="{ text:'more...', to:'/' }"
>
    <Activity :track="track" :user="user" />
    <Activity :track="track" :user="user" />
    <Activity :track="track" :user="user" />
</Section>
</Layout>
```

<Layout flex>
<Toggle v-model="alignLeft" label="Left-align the layout"/>
</Layout>

---

<Spacer />

<Layout stack gap-64 class="preview" style="margin: 0 -40px; padding: 0 25px;">

<Section :alignLeft="alignLeft" small-items h3="Cards (small items)" :action="{ text:'Documentation on Cards', to:'../card' }">
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
    <Card small title="Relatively Long Album Name">
        Artist Name
    </Card>
</Section>

<Section :alignLeft="alignLeft" medium-items h3="Activities (medium items)" :action="{ text:'Delete selected items', onClick:()=>console.log('Deleted :-)') }">
    <Activity :track="track" :user="user" />
    <Activity :track="track" :user="user" />
    <Activity :track="track" :user="user" />
</Section>

</Layout>

## Responsivity

- Cards and Activities snap to the grid columns. They have intrinsic widths, expressed in the number of columns they span. For Card, it is 3 and for Activity, it is 4.
- On a typical laptop screen, you will have 4 albums or 3 activities side-by-side. On a typical mobile screen, you will have 1 medium card or 2 small ones in a row.
- The remaining space is evenly distributed.
- Title rows align with the content below them.

Resize the window to observe how the items move.