Skip to content

Commit 5adb27d

Browse files
ThornWalliThornWalli
committed
fix(update): added usage; improve
1 parent 2cde378 commit 5adb27d

13 files changed

+288
-97
lines changed

‎docs/.vitepress/navigation.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ export default {
1010
text: 'Guide',
1111
items: [
1212
{ text: 'Introduction', link: '/introduction' },
13-
{ text: 'Setup', link: '/setup' }
13+
{ text: 'Setup', link: '/setup' },
14+
{ text: 'Usage', link: '/usage' }
1415
]
1516
},
1617
{

‎docs/src/introduction.md

Lines changed: 14 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -33,27 +33,22 @@ If `ContentContainer` is level 2, `ContentHeadline` level 2 is rendered as `h2`.
3333
<div>
3434
<header>Header</header>
3535
<ContentContainer>
36-
<div>
36+
<header>
3737
<ContentHeadline> Primary Headline (h1) </ContentHeadline>
38-
</div>
38+
</header>
3939
<ContentContainer>
4040
<ContentHeadline> Secondary Headline 1 (h2) </ContentHeadline>
4141
<ContentContainer>
42-
<ContentContainer>
43-
<ContentHeadline> Tertiary Headline 1.1 (h3) </ContentHeadline>
44-
</ContentContainer>
45-
<ContentContainer>
46-
<ContentHeadline> Tertiary Headline 1.2 (h3) </ContentHeadline>
47-
</ContentContainer>
42+
<ContentHeadline> Tertiary Headline 1.1 (h3) </ContentHeadline>
43+
</ContentContainer>
44+
<ContentContainer>
45+
<ContentHeadline> Tertiary Headline 1.2 (h3) </ContentHeadline>
4846
</ContentContainer>
4947
</ContentContainer>
50-
</ContentContainer>
5148
<ContentContainer>
5249
<ContentHeadline> Secondary Headline 2 (h2) </ContentHeadline>
5350
<ContentContainer>
54-
<ContentContainer>
55-
<ContentHeadline> Tertiary Headline 2.1 (h3) </ContentHeadline>
56-
</ContentContainer>
51+
<ContentHeadline> Tertiary Headline 2.1 (h3) </ContentHeadline>
5752
</ContentContainer>
5853
</ContentContainer>
5954
</ContentContainer>
@@ -66,26 +61,22 @@ If `ContentContainer` is level 2, `ContentHeadline` level 2 is rendered as `h2`.
6661
<div>
6762
<header>Header</header>
6863
<main>
69-
<div>
64+
<header>
7065
<h1> Primary Headline (h1) </h1>
71-
</div>
66+
</header>
7267
<article>
7368
<h2> Secondary Headline 1 (h2) </h2>
7469
<section>
75-
<article>
76-
<h3> Tertiary Headline 1.1 (h3) </h3>
77-
</article>
78-
<article>
79-
<h3> Tertiary Headline 1.2 (h3) </h3>
80-
</article>
70+
<h3> Tertiary Headline 1.1 (h3) </h3>
71+
</section>
72+
<section>
73+
<h3> Tertiary Headline 1.2 (h3) </h3>
8174
</section>
8275
</article>
8376
<article>
8477
<h2> Secondary Headline 2 (h2) </h2>
8578
<section>
86-
<article>
87-
<h3> Tertiary Headline 2.1 (h3) </h3>
88-
</article>
79+
<h3> Tertiary Headline 2.1 (h3) </h3>
8980
</section>
9081
</article>
9182
</main>

‎docs/src/usage.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Usage
3+
---
4+
5+
# {{$frontmatter.title}}
6+
7+
The standard behavior of `vue-semantic-structure` defines the most common approach for the use of HTML structure components.
8+
9+
In this structure, the main content contains different modules *(example: Stage (Hero), Text-Image, Gallery, etc.)*.
10+
11+
The main structure is in the `<main>` tag, which contains the main components.
12+
13+
::: code-group
14+
15+
```html [HTML]
16+
<main>
17+
<header class="hero">…</header>
18+
<section class="text-image">…</section>
19+
<section class="gallery">…</section>
20+
</main>
21+
```
22+
23+
```vue [Vue]
24+
<template>
25+
<ContentContainer>
26+
<header class="hero">…</header>
27+
<ContentContainer class="text-image">…</ContentContainer>
28+
<ContentContainer class="gallery">…</ContentContainer>
29+
</ContentContainer>
30+
</template>
31+
```
32+
33+
:::
34+
35+
## Advance Usage
36+
37+
The behavior of the `ContentContainer` can also be adapted for blog article pages.
38+
39+
Here, an `<article>` is often used in the `<main>` tag, for which the `ContentContainer` must be adapted.
40+
41+
The `rootTags` property must be extended by an `<article>` (e.g. `['main', 'article']`).
42+
43+
It is recommended to create a separate component that extends the `ContentContainer`.
44+
45+
### `CustomContentContainer.vue`
46+
47+
```vue
48+
<template>
49+
<ContentContainer :root-tags="['main', 'article']">
50+
<slot />
51+
</ContentContainer>
52+
</template>
53+
54+
<script setup>
55+
import { ContentContainer } from 'vue-semantic-structure';
56+
</script>
57+
```
58+
59+
In comparison to the basic application, the entire content is enclosed in another `CustomContentContainer` (e.g. `ContentContainer`), which represents the `<article>` tag.
60+
61+
::: code-group
62+
63+
```html [HTML]
64+
<main>
65+
<article>
66+
<header class="hero">…</header>
67+
<section class="text-image">…</section>
68+
<section class="gallery">…</section>
69+
</article>
70+
</main>
71+
```
72+
73+
```vue [Vue]
74+
<template>
75+
<CustomContentContainer>
76+
<CustomContentContainer>
77+
<header class="hero">…</header>
78+
<CustomContentContainer class="text-image">…</CustomContentContainer>
79+
<CustomContentContainer class="gallery">…</CustomContentContainer>
80+
</CustomContentContainer>
81+
</CustomContentContainer>
82+
</template>
83+
```
84+
85+
:::

‎playground/src/App.vue

Lines changed: 50 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<template>
22
<div>
3-
<DefaultContentContainer debug>
3+
<BasicContentContainer debug>
44
<header>
55
<DebugHeadline>Stage</DebugHeadline>
66
<p>
@@ -9,56 +9,54 @@
99
</p>
1010
<pre class="structure-debug" data-debug-current-tag="header"></pre>
1111
</header>
12-
<DefaultContentContainer>
13-
<DefaultContentContainer>
14-
<DebugHeadline>Text Component</DebugHeadline>
15-
<p>
16-
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
17-
dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
18-
clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,
19-
consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
20-
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
21-
sea takimata sanctus est Lorem ipsum dolor sit amet.
22-
</p>
23-
</DefaultContentContainer>
24-
<DefaultContentContainer>
25-
<DebugHeadline>Gallery Component</DebugHeadline>
26-
<p>
27-
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
28-
dolore magna aliquyam.
29-
</p>
30-
<div class="gallery columns-4">
31-
<div v-for="(item, index) in Array(4)" :key="index"></div>
32-
</div>
33-
</DefaultContentContainer>
34-
<DefaultContentContainer>
35-
<DebugHeadline>Teasers Component</DebugHeadline>
36-
<div class="columns-3">
37-
<DefaultContentContainer>
38-
<DebugHeadline>Teaser 1</DebugHeadline>
39-
<p>
40-
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
41-
labore et dolore magna aliquyam erat, sed diam voluptua.
42-
</p>
43-
</DefaultContentContainer>
44-
<DefaultContentContainer>
45-
<DebugHeadline>Teaser 2</DebugHeadline>
46-
<p>
47-
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
48-
labore et dolore magna aliquyam erat, sed diam voluptua.
49-
</p>
50-
</DefaultContentContainer>
51-
<DefaultContentContainer>
52-
<DebugHeadline>Teaser 3</DebugHeadline>
53-
<p>
54-
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
55-
labore et dolore magna aliquyam erat, sed diam voluptua.
56-
</p>
57-
</DefaultContentContainer>
58-
</div>
59-
</DefaultContentContainer>
60-
</DefaultContentContainer>
61-
</DefaultContentContainer>
12+
<BasicContentContainer>
13+
<DebugHeadline>Text Component</DebugHeadline>
14+
<p>
15+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
16+
dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
17+
clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,
18+
consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
19+
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea
20+
takimata sanctus est Lorem ipsum dolor sit amet.
21+
</p>
22+
</BasicContentContainer>
23+
<BasicContentContainer>
24+
<DebugHeadline>Gallery Component</DebugHeadline>
25+
<p>
26+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
27+
dolore magna aliquyam.
28+
</p>
29+
<div class="gallery columns-4">
30+
<div v-for="(item, index) in Array(4)" :key="index"></div>
31+
</div>
32+
</BasicContentContainer>
33+
<BasicContentContainer>
34+
<DebugHeadline>Teasers Component</DebugHeadline>
35+
<div class="columns-3">
36+
<BasicContentContainer>
37+
<DebugHeadline>Teaser 1</DebugHeadline>
38+
<p>
39+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
40+
et dolore magna aliquyam erat, sed diam voluptua.
41+
</p>
42+
</BasicContentContainer>
43+
<BasicContentContainer>
44+
<DebugHeadline>Teaser 2</DebugHeadline>
45+
<p>
46+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
47+
et dolore magna aliquyam erat, sed diam voluptua.
48+
</p>
49+
</BasicContentContainer>
50+
<BasicContentContainer>
51+
<DebugHeadline>Teaser 3</DebugHeadline>
52+
<p>
53+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
54+
et dolore magna aliquyam erat, sed diam voluptua.
55+
</p>
56+
</BasicContentContainer>
57+
</div>
58+
</BasicContentContainer>
59+
</BasicContentContainer>
6260

6361
<hr />
6462

@@ -130,7 +128,7 @@
130128
import DebugHeadline from '@/components/DebugHeadline.vue';
131129
import GithubCorner from './components/GithubCorner.vue';
132130
import ArticleContentContainer from './components/ArticleContentContainer.vue';
133-
import DefaultContentContainer from './components/DefaultContentContainer.vue';
131+
import BasicContentContainer from './components/BasicContentContainer.vue';
134132
135133
const GITHUB_URL = import.meta.env.VITE_GITHUB_URL;
136134
</script>

‎playground/src/components/ArticleContentContainer.vue

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
<template>
22
<ContentContainer
3-
:contentTags="['article', 'section']"
43
:rootTags="['main', 'article']"
54
v-slot="{ parentLevel, currentLevel, currentTag }"
65
:data-debug="isDebug ? 'container' : undefined">

‎playground/src/components/DefaultContentContainer.vue renamed to ‎playground/src/components/BasicContentContainer.vue

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
<template>
22
<ContentContainer
3-
:contentTags="['section', 'article']"
4-
:rootTags="['main', undefined]"
3+
:rootTags="['main']"
54
v-slot="{ parentLevel, currentLevel, currentTag }"
65
:data-debug="isDebug ? 'container' : undefined">
76
<slot />

‎src/ContentContainer.vue

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,13 @@ export default {
3434
contentTags: {
3535
type: Array,
3636
default() {
37-
return ['section', 'article'];
37+
return ['article', 'section'];
3838
}
3939
},
4040
rootTags: {
4141
type: Array,
4242
default() {
43-
return ['main', null];
43+
return ['main'];
4444
}
4545
},
4646
level: {

‎src/useContentContainer.js

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,19 @@ import { provide, inject, computed } from 'vue';
22

33
export default function useContentContainer({ tag, contentTags, rootTags, level } = {}) {
44
tag = tag || null;
5-
contentTags = contentTags || ['section', 'article'];
6-
rootTags = rootTags || ['main', null];
5+
contentTags = contentTags || ['article', 'section'];
6+
rootTags = rootTags || ['main'];
77
level = level || undefined;
8-
const parentLevel = inject('parentLevel', 0);
98

9+
const parentLevel = inject('parentLevel', 0);
1010
const currentLevel = computed(() => (level !== undefined ? level : parentLevel + 1));
11-
1211
const currentTag = computed(() => {
1312
if (tag) {
1413
return tag;
1514
}
1615
if (Number(parentLevel) in rootTags) {
1716
return rootTags[Number(parentLevel)];
1817
}
19-
2018
return contentTags[currentLevel.value % contentTags.length];
2119
});
2220

‎src/useContentHeadline.js

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { inject, computed } from 'vue';
33
export default function useContentHeadline({ tag } = {}) {
44
const parentLevel = inject('parentLevel', 1) + 1;
55
const rootLevel = inject('rootLevel', 1);
6-
const getMax = number => Math.max(1, Math.min(number, 6));
6+
77
const currentLevel = computed(() => getMax(parentLevel - rootLevel));
88
const currentTag = computed(() => tag || `h${currentLevel.value}`);
99

@@ -12,3 +12,5 @@ export default function useContentHeadline({ tag } = {}) {
1212
currentTag
1313
};
1414
}
15+
16+
const getMax = number => Math.max(1, Math.min(number, 6));

‎test/contentContainer.test.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ describe('ContentContainer', () => {
2929

3030
const wrapper = mount(root);
3131
expect(wrapper.find(`main>article>section>article>section`).text()).toBe('Test');
32-
const needsd = ['main', null, 'article'];
32+
const needsd = ['main', 'article'];
3333
needsd.forEach((tag, index) => {
3434
if (tag) {
3535
expect(wrapper.find(`[data-current-level="${index + 1}"]`).attributes('data-parent-level')).toBe(String(index));

‎test/contentHeadline.test.js

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ describe('contentHeadline', () => {
1515
components: { ContentContainer, ContentHeadline: DebugContentHeadline },
1616
template: `
1717
<ContentContainer>
18+
<ContentHeadline />
1819
<ContentContainer>
1920
<ContentHeadline />
2021
<ContentContainer>
@@ -25,9 +26,6 @@ describe('contentHeadline', () => {
2526
<ContentHeadline />
2627
<ContentContainer>
2728
<ContentHeadline />
28-
<ContentContainer>
29-
<ContentHeadline />
30-
</ContentContainer>
3129
</ContentContainer>
3230
</ContentContainer>
3331
</ContentContainer>

‎test/useContentContainer.test.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ describe('useContentContainer', () => {
3636

3737
const wrapper = mount(root);
3838
expect(wrapper.find(`main>article>section>article>section`).text()).toBe('Test');
39-
const needsd = ['main', null, 'article'];
39+
const needsd = ['main', 'article'];
4040
needsd.forEach((tag, index) => {
4141
if (tag) {
4242
expect(wrapper.find(`[data-current-level="${index + 1}"]`).attributes('data-parent-level')).toBe(String(index));

0 commit comments

Comments
 (0)