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

<script setup lang="ts">
import { 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') }" />

## Set gaps between consecutive sections

Place consecutive sections into a [Layout stack](../layout) with a 64px gap (`gap-64`) to give them a regular vertical rhythm. Use different sizes for very small or very large headings.

Note the spacer above the layout. By default, sections begin at the baseline of the heading. This enables us to explicitly define the vertical rhythm, independently of the heading's line height.

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

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

<Spacer />

## Mix sections of different item widths

```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 may have 4 album cards or 3 activities side-by-side. On a typical mobile screen, you will have one medium card or two small ones in a row.
- The remaining space is evenly distributed.
- Title rows align with the content below them. The action on the right will always end with the last item in the grid. Resize the window to observe how the items move.