fix(update): added usage; improve

basics · Sep 24, 2024 · 5adb27d · 5adb27d
1 parent 2cde378
commit 5adb27d
Show file tree

Hide file tree

Showing 13 changed files with 288 additions and 97 deletions.
diff --git a/docs/.vitepress/navigation.js b/docs/.vitepress/navigation.js
@@ -10,7 +10,8 @@ export default {
       text: 'Guide',
       items: [
         { text: 'Introduction', link: '/introduction' },
-        { text: 'Setup', link: '/setup' }
+        { text: 'Setup', link: '/setup' },
+        { text: 'Usage', link: '/usage' }
       ]
     },
     {

diff --git a/docs/src/introduction.md b/docs/src/introduction.md
@@ -33,27 +33,22 @@ If `ContentContainer` is level 2, `ContentHeadline` level 2 is rendered as `h2`.
   <div>
     <header>Header</header>
     <ContentContainer>
-      <div>
+      <header>
         <ContentHeadline> Primary Headline (h1) </ContentHeadline>
-      </div>
+      </header>
       <ContentContainer>
         <ContentHeadline> Secondary Headline 1 (h2) </ContentHeadline>
         <ContentContainer>
-          <ContentContainer>
-            <ContentHeadline> Tertiary Headline 1.1 (h3) </ContentHeadline>
-          </ContentContainer>
-          <ContentContainer>
-            <ContentHeadline> Tertiary Headline 1.2 (h3) </ContentHeadline>
-          </ContentContainer>
+          <ContentHeadline> Tertiary Headline 1.1 (h3) </ContentHeadline>
+        </ContentContainer>
+        <ContentContainer>
+          <ContentHeadline> Tertiary Headline 1.2 (h3) </ContentHeadline>
         </ContentContainer>
       </ContentContainer>
-    </ContentContainer>
       <ContentContainer>
         <ContentHeadline> Secondary Headline 2 (h2) </ContentHeadline>
         <ContentContainer>
-          <ContentContainer>
-            <ContentHeadline> Tertiary Headline 2.1 (h3) </ContentHeadline>
-          </ContentContainer>
+          <ContentHeadline> Tertiary Headline 2.1 (h3) </ContentHeadline>
         </ContentContainer>
       </ContentContainer>
     </ContentContainer>
@@ -66,26 +61,22 @@ If `ContentContainer` is level 2, `ContentHeadline` level 2 is rendered as `h2`.
 <div>
   <header>Header</header>
   <main>
-    <div>
+    <header>
       <h1> Primary Headline (h1) </h1>
-    </div>
+    </header>
     <article>
       <h2> Secondary Headline 1 (h2) </h2>
       <section>
-        <article>
-          <h3> Tertiary Headline 1.1 (h3) </h3>
-        </article>
-        <article>
-          <h3> Tertiary Headline 1.2 (h3) </h3>
-        </article>
+        <h3> Tertiary Headline 1.1 (h3) </h3>
+      </section>
+      <section>
+        <h3> Tertiary Headline 1.2 (h3) </h3>
       </section>
     </article>
     <article>
       <h2> Secondary Headline 2 (h2) </h2>
       <section>
-        <article>
-          <h3> Tertiary Headline 2.1 (h3) </h3>
-        </article>
+        <h3> Tertiary Headline 2.1 (h3) </h3>
       </section>
     </article>
   </main>

diff --git a/docs/src/usage.md b/docs/src/usage.md
@@ -0,0 +1,85 @@
+---
+title: Usage
+---
+
+# {{$frontmatter.title}}
+
+The standard behavior of `vue-semantic-structure` defines the most common approach for the use of HTML structure components.
+
+In this structure, the main content contains different modules *(example: Stage (Hero), Text-Image, Gallery, etc.)*.
+
+The main structure is in the `<main>` tag, which contains the main components.
+
+::: code-group
+
+```html [HTML]
+<main>
+  <header class="hero">…</header>
+  <section class="text-image">…</section>
+  <section class="gallery">…</section>
+</main>
+```
+
+```vue [Vue]
+<template>
+  <ContentContainer>
+    <header class="hero">…</header>
+    <ContentContainer class="text-image">…</ContentContainer>
+    <ContentContainer class="gallery">…</ContentContainer>
+  </ContentContainer>
+</template>
+```
+
+:::
+
+## Advance Usage
+
+The behavior of the `ContentContainer` can also be adapted for blog article pages.
+
+Here, an `<article>` is often used in the `<main>` tag, for which the `ContentContainer` must be adapted.
+
+The `rootTags` property must be extended by an `<article>` (e.g. `['main', 'article']`).
+
+It is recommended to create a separate component that extends the `ContentContainer`.
+
+### `CustomContentContainer.vue`
+
+```vue
+<template>
+  <ContentContainer :root-tags="['main', 'article']">
+    <slot />
+  </ContentContainer>
+</template>
+
+<script setup>
+import { ContentContainer } from 'vue-semantic-structure';
+</script>
+```
+
+In comparison to the basic application, the entire content is enclosed in another `CustomContentContainer` (e.g. `ContentContainer`), which represents the `<article>` tag.
+
+::: code-group
+
+```html [HTML]
+<main>
+  <article>
+    <header class="hero">…</header>
+    <section class="text-image">…</section>
+    <section class="gallery">…</section>
+  </article>
+</main>
+```
+
+```vue [Vue]
+<template>
+  <CustomContentContainer>
+    <CustomContentContainer>
+      <header class="hero">…</header>
+      <CustomContentContainer class="text-image">…</CustomContentContainer>
+      <CustomContentContainer class="gallery">…</CustomContentContainer>
+    </CustomContentContainer>
+  </CustomContentContainer>
+</template>
+```
+
+:::
diff --git a/playground/src/App.vue b/playground/src/App.vue
@@ -1,6 +1,6 @@
 <template>
   <div>
-    <DefaultContentContainer debug>
+    <BasicContentContainer debug>
       <header>
         <DebugHeadline>Stage</DebugHeadline>
         <p>
@@ -9,56 +9,54 @@
         </p>
         <pre class="structure-debug" data-debug-current-tag="header"></pre>
       </header>
-      <DefaultContentContainer>
-        <DefaultContentContainer>
-          <DebugHeadline>Text Component</DebugHeadline>
-          <p>
-            Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
-            dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
-            clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,
-            consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-            sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no
-            sea takimata sanctus est Lorem ipsum dolor sit amet.
-          </p>
-        </DefaultContentContainer>
-        <DefaultContentContainer>
-          <DebugHeadline>Gallery Component</DebugHeadline>
-          <p>
-            Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
-            dolore magna aliquyam.
-          </p>
-          <div class="gallery columns-4">
-            <div v-for="(item, index) in Array(4)" :key="index"></div>
-          </div>
-        </DefaultContentContainer>
-        <DefaultContentContainer>
-          <DebugHeadline>Teasers Component</DebugHeadline>
-          <div class="columns-3">
-            <DefaultContentContainer>
-              <DebugHeadline>Teaser 1</DebugHeadline>
-              <p>
-                Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
-                labore et dolore magna aliquyam erat, sed diam voluptua.
-              </p>
-            </DefaultContentContainer>
-            <DefaultContentContainer>
-              <DebugHeadline>Teaser 2</DebugHeadline>
-              <p>
-                Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
-                labore et dolore magna aliquyam erat, sed diam voluptua.
-              </p>
-            </DefaultContentContainer>
-            <DefaultContentContainer>
-              <DebugHeadline>Teaser 3</DebugHeadline>
-              <p>
-                Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut
-                labore et dolore magna aliquyam erat, sed diam voluptua.
-              </p>
-            </DefaultContentContainer>
-          </div>
-        </DefaultContentContainer>
-      </DefaultContentContainer>
-    </DefaultContentContainer>
+      <BasicContentContainer>
+        <DebugHeadline>Text Component</DebugHeadline>
+        <p>
+          Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
+          dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
+          clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,
+          consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
+          sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea
+          takimata sanctus est Lorem ipsum dolor sit amet.
+        </p>
+      </BasicContentContainer>
+      <BasicContentContainer>
+        <DebugHeadline>Gallery Component</DebugHeadline>
+        <p>
+          Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et
+          dolore magna aliquyam.
+        </p>
+        <div class="gallery columns-4">
+          <div v-for="(item, index) in Array(4)" :key="index"></div>
+        </div>
+      </BasicContentContainer>
+      <BasicContentContainer>
+        <DebugHeadline>Teasers Component</DebugHeadline>
+        <div class="columns-3">
+          <BasicContentContainer>
+            <DebugHeadline>Teaser 1</DebugHeadline>
+            <p>
+              Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
+              et dolore magna aliquyam erat, sed diam voluptua.
+            </p>
+          </BasicContentContainer>
+          <BasicContentContainer>
+            <DebugHeadline>Teaser 2</DebugHeadline>
+            <p>
+              Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
+              et dolore magna aliquyam erat, sed diam voluptua.
+            </p>
+          </BasicContentContainer>
+          <BasicContentContainer>
+            <DebugHeadline>Teaser 3</DebugHeadline>
+            <p>
+              Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore
+              et dolore magna aliquyam erat, sed diam voluptua.
+            </p>
+          </BasicContentContainer>
+        </div>
+      </BasicContentContainer>
+    </BasicContentContainer>
 
     <hr />
 
@@ -130,7 +128,7 @@
 import DebugHeadline from '@/components/DebugHeadline.vue';
 import GithubCorner from './components/GithubCorner.vue';
 import ArticleContentContainer from './components/ArticleContentContainer.vue';
-import DefaultContentContainer from './components/DefaultContentContainer.vue';
+import BasicContentContainer from './components/BasicContentContainer.vue';
 
 const GITHUB_URL = import.meta.env.VITE_GITHUB_URL;
 </script>

diff --git a/playground/src/components/ArticleContentContainer.vue b/playground/src/components/ArticleContentContainer.vue
@@ -1,6 +1,5 @@
 <template>
   <ContentContainer
-    :contentTags="['article', 'section']"
     :rootTags="['main', 'article']"
     v-slot="{ parentLevel, currentLevel, currentTag }"
     :data-debug="isDebug ? 'container' : undefined">

diff --git a/...rc/components/DefaultContentContainer.vue → .../src/components/BasicContentContainer.vue b/...rc/components/DefaultContentContainer.vue → .../src/components/BasicContentContainer.vue
@@ -1,7 +1,6 @@
 <template>
   <ContentContainer
-    :contentTags="['section', 'article']"
-    :rootTags="['main', undefined]"
+    :rootTags="['main']"
     v-slot="{ parentLevel, currentLevel, currentTag }"
     :data-debug="isDebug ? 'container' : undefined">
     <slot />

diff --git a/src/ContentContainer.vue b/src/ContentContainer.vue
@@ -34,13 +34,13 @@ export default {
     contentTags: {
       type: Array,
       default() {
-        return ['section', 'article'];
+        return ['article', 'section'];
       }
     },
     rootTags: {
       type: Array,
       default() {
-        return ['main', null];
+        return ['main'];
       }
     },
     level: {

diff --git a/src/useContentContainer.js b/src/useContentContainer.js
@@ -2,21 +2,19 @@ import { provide, inject, computed } from 'vue';
 
 export default function useContentContainer({ tag, contentTags, rootTags, level } = {}) {
   tag = tag || null;
-  contentTags = contentTags || ['section', 'article'];
-  rootTags = rootTags || ['main', null];
+  contentTags = contentTags || ['article', 'section'];
+  rootTags = rootTags || ['main'];
   level = level || undefined;
-  const parentLevel = inject('parentLevel', 0);
 
+  const parentLevel = inject('parentLevel', 0);
   const currentLevel = computed(() => (level !== undefined ? level : parentLevel + 1));
-
   const currentTag = computed(() => {
     if (tag) {
       return tag;
     }
     if (Number(parentLevel) in rootTags) {
       return rootTags[Number(parentLevel)];
     }
-
     return contentTags[currentLevel.value % contentTags.length];
   });
 

diff --git a/src/useContentHeadline.js b/src/useContentHeadline.js
@@ -3,7 +3,7 @@ import { inject, computed } from 'vue';
 export default function useContentHeadline({ tag } = {}) {
   const parentLevel = inject('parentLevel', 1) + 1;
   const rootLevel = inject('rootLevel', 1);
-  const getMax = number => Math.max(1, Math.min(number, 6));
+
   const currentLevel = computed(() => getMax(parentLevel - rootLevel));
   const currentTag = computed(() => tag || `h${currentLevel.value}`);
 
@@ -12,3 +12,5 @@ export default function useContentHeadline({ tag } = {}) {
     currentTag
   };
 }
+
+const getMax = number => Math.max(1, Math.min(number, 6));
diff --git a/test/contentContainer.test.js b/test/contentContainer.test.js
@@ -29,7 +29,7 @@ describe('ContentContainer', () => {
 
     const wrapper = mount(root);
     expect(wrapper.find(`main>article>section>article>section`).text()).toBe('Test');
-    const needsd = ['main', null, 'article'];
+    const needsd = ['main', 'article'];
     needsd.forEach((tag, index) => {
       if (tag) {
         expect(wrapper.find(`[data-current-level="${index + 1}"]`).attributes('data-parent-level')).toBe(String(index));

diff --git a/test/contentHeadline.test.js b/test/contentHeadline.test.js
@@ -15,6 +15,7 @@ describe('contentHeadline', () => {
       components: { ContentContainer, ContentHeadline: DebugContentHeadline },
       template: `
   <ContentContainer>
+    <ContentHeadline />
     <ContentContainer>
       <ContentHeadline />
       <ContentContainer>
@@ -25,9 +26,6 @@ describe('contentHeadline', () => {
             <ContentHeadline />
             <ContentContainer>
               <ContentHeadline />
-              <ContentContainer>
-                <ContentHeadline />
-              </ContentContainer>
             </ContentContainer>
           </ContentContainer>
         </ContentContainer>

diff --git a/test/useContentContainer.test.js b/test/useContentContainer.test.js
@@ -36,7 +36,7 @@ describe('useContentContainer', () => {
 
     const wrapper = mount(root);
     expect(wrapper.find(`main>article>section>article>section`).text()).toBe('Test');
-    const needsd = ['main', null, 'article'];
+    const needsd = ['main', 'article'];
     needsd.forEach((tag, index) => {
       if (tag) {
         expect(wrapper.find(`[data-current-level="${index + 1}"]`).attributes('data-parent-level')).toBe(String(index));