feat(doc): add <SDoc> (#413)

docs/.vitepress/config.mts

@@ -61,6 +61,8 @@ function sidebar(): DefaultTheme.SidebarItem[] {
         { text: 'SCard', link: '/components/card' },
         { text: 'SContent', link: '/components/content' },
         { text: 'SDesc', link: '/components/desc' },
+        { text: 'SDivider', link: '/components/divider' },
+        { text: 'SDoc', link: '/components/doc' },
         { text: 'SErrorBoundary', link: '/components/error-boundary' },
         { text: 'SFragment', link: '/components/fragment' },
         { text: 'SGrid', link: '/components/grid' },

docs/components/card.md

@@ -232,11 +232,11 @@ Use `<SCardBlock>` to display generic block element. This component is usually u
 
 ### Block spacing
 
-The `<SCardBlock>` component provides a convenient way to control the padding of the block using the `:space` prop. You can choose between two values: `compact` or `wide`.
+The `<SCardBlock>` component provides a convenient way to control the padding of the block using the `:space` prop. You can choose between 3 values: `compact`, `wide`, or `xwide`.
 
 ```ts
 interface Props {
-  space?: 'compact' | 'wide'
+  space?: 'compact' | 'wide' | 'xwide'
 }
 ```
 
@@ -248,7 +248,7 @@ interface Props {
 </SCard>
 ```
 
-To ensure consistent spacing across the application, you should adjust the spacing based on the size of the `<SCard>` component. Consider using the `compact` class for card widths smaller than `640px` and the `wide` class for larger widths.
+To ensure consistent spacing across the application, you should adjust the spacing based on the size of the `<SCard>` component. Consider using the `compact` class for card width smaller than `640px` and the `wide` class for larger widths. Use `xwide` for the card containing form and placed sorely on the page (not as modal dialog).
 
 ## Footer
 
@@ -290,11 +290,11 @@ export interface Tooltip {
 
 ### Footer spacing
 
-Same as, `<SCardBlock>`, `<SCardFooter>` also comes with `:space` props that lets you control the padding of the block. You may pass either `compact` or `wide` as a value.
+Same as, `<SCardBlock>`, `<SCardFooter>` also comes with `:space` props that lets you control the padding of the block. You may pass either `compact`, `wide` or `xwide` as a value.
 
 ```ts
 interface Props {
-  space?: 'compact' | 'wide'
+  space?: 'compact' | 'wide' | `xwide`
 }
 ```
 
@@ -306,6 +306,4 @@ interface Props {
 </SCard>
 ```
 
-To ensure consistent spacing across the application, you should adjust the spacing based on the size of the `<SCard>` component. Consider using the `compact` class for card widths smaller than `640px` and the `wide` class for larger widths.
-
 It's important to align this spacing with the `<SCardBlock>` component to ensure proper alignment between the block contents and the footer contents, such as actions.

docs/components/content.md

@@ -11,6 +11,7 @@ import SContent from 'sefirot/components/SContent.vue'
   story="/stories-components-scontent-01-playground-story-vue"
 >
   <SContent>
+    <h2>Title of the section</h2>
     <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
     <ul>
       <li>Excepteur sint occaecat cupidatat.</li>
@@ -20,17 +21,20 @@ import SContent from 'sefirot/components/SContent.vue'
   </SContent>
 </Showcase>
 
+## Import
+
+```ts
+import SContent from '@globalbrain/sefirot/lib/components/SContent.vue'
+```
+
 ## Usage
 
 Place HTML elements inside `<SContent>` component and it will apply basic styles to the element, including spacing between elements.
 
-```vue
-<script setup lang="ts">
-import SContent from '@globalbrain/sefirot/lib/components/SContent.vue'
-</script>
-
+```vue-html
 <template>
   <SContent>
+    <h2>Title of the section</h2>
     <p>Lorem ipsum dolor sit amet.</p>
     <p>Consectetur adipiscing elit.</p>
     <ul>
@@ -44,9 +48,21 @@ import SContent from '@globalbrain/sefirot/lib/components/SContent.vue'
 
 The supported elements are:
 
+- `<h1>` <Badge text="3.11.0" />
+- `<h2>` <Badge text="3.11.0" />
 - `<p>`
 - `<strong>`
 - `<a>`
 - `<ul>`
 - `<ol>`
 - `<li>`
+
+### Use CSS class to style the headings
+
+You may use css class either `h1` or `h2` to apply the styles to the element.
+
+```vue-html
+<SContent>
+  <p class="h1">Title text</p>
+</SContent>
+```

docs/components/divider.md

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import SDivider from 'sefirot/components/SDivider.vue'
+</script>
+
+# SDivider <Badge text="3.11.0" />
+
+`<SDivider>` is a component to display a horizontal line.
+
+<Showcase
+  path="/components/SDivider.vue"
+  story="/stories-components-sdivider-01-playground-story-vue"
+>
+  <SDivider />
+</Showcase>
+
+## Import
+
+```ts
+import SDivider from '@globalbrain/sefirot/lib/components/SDivider.vue'
+```
+
+## Usage
+
+Place `<SDivider>` anywhere you want to display a horizontal line.
+
+```vue-html
+<SDivider />
+```

docs/components/doc.md

@@ -0,0 +1,90 @@
+# SDoc <Badge text="3.11.0" />
+
+`<SDoc>` is a component to display a doc style contents. It controls the nested element styles and spacing to have a consistent look and feel.
+
+## Import
+
+```ts
+import SDoc from '@globalbrain/sefirot/lib/components/SDoc.vue'
+import SDocSection from '@globalbrain/sefirot/lib/components/SDocSection.vue'
+```
+
+## Usage
+
+Nest the elements inside `<SDoc>` component and it will apply basic styles to the element, including spacing between elements.
+
+Most of the time, you should be using [`<SContent>`](content) to build title and description section, [`<SDivider>`](divider) to display section divider, and the use [`<SGrid>`](grid) to show form elements.
+
+```vue-html
+<SDoc>
+  <SContent>
+    <h1>Title of the content</h1>
+    <p>Lorem ipsum...</p>
+  </SContent>
+
+  <SDivider />
+
+  <SContent>
+    <h2>Section title</h2>
+    <p>Lorem ipsum...</p>
+  </SContent>
+
+  <SGrid gap="24">
+    <SGridItem>
+      <SInputText
+        label="Name"
+        placeholder="John Doe"
+        :model-value="null"
+      />
+    </SGridItem>
+
+    <SGridItem>
+      <SInputText
+        type="email"
+        label="Email"
+        placeholder="john.doe@example.com"
+        :model-value="null"
+      />
+    </SGridItem>
+  </SGrid>
+</SDoc>
+```
+
+You may use `<SDocSection>` to organize the content into sections. There is no difference in terms of stylings, but it helps organize your code when the content is large. It also helps code editor to collapse the section. You could add class name to the section to make it readable too.
+
+```vue-html
+<SDoc>
+  <SDocSection class="header">
+    <SContent>
+      <h1>Title of the content</h1>
+      <p>Lorem ipsum...</p>
+    </SContent>
+  </SDocSection>
+
+  <SDivider />
+
+  <SDocSection class="account-info">
+    <SContent>
+      <h2>Section title</h2>
+      <p>Lorem ipsum...</p>
+    </SContent>
+    <SGrid gap="24">
+      <SGridItem>
+        <SInputText
+          label="Name"
+          placeholder="John Doe"
+          :model-value="null"
+        />
+      </SGridItem>
+      <SGridItem>
+        <SInputText
+          type="email"
+          label="Email"
+          placeholder="john.doe@example.com"
+          :model-value="null"
+        />
+      </SGridItem>
+    </SGrid>
+  </SDocSection>
+</SDoc>
+```

lib/components/SCardBlock.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-export type Space = 'compact' | 'wide'
+export type Space = 'compact' | 'wide' | 'xwide'
 
 defineProps<{
   space?: Space
@@ -19,6 +19,7 @@ defineProps<{
 
   &.compact { padding: 24px; }
   &.wide    { padding: 32px; }
+  &.xwide   { padding: 48px; }
 }
 
 .SCard > .SCardBlock:first-child {

lib/components/SCardFooter.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-export type Space = 'compact' | 'wide'
+export type Space = 'compact' | 'wide' | 'xwide'
 
 defineProps<{
   space?: Space

lib/components/SCardFooterActions.vue

@@ -13,5 +13,6 @@
 
   .SCardFooter.compact > & { padding: 12px 24px; }
   .SCardFooter.wide > &    { padding: 16px 32px; }
+  .SCardFooter.xwide > &   { padding: 24px 48px; }
 }
 </style>

lib/components/SContent.vue

@@ -11,8 +11,31 @@
   gap: 12px;
 }
 
+.SContent :deep(h1),
+.SContent :deep(.h1) {
+  margin: 0;
+  max-width: 640px;
+  line-height: 40px;
+  font-size: 32px;
+  font-weight: 500;
+  color: var(--c-text-1);
+}
+
+.SContent :deep(h2),
+.SContent :deep(.h2) {
+  border-top: 0;
+  margin: 0;
+  padding: 0;
+  max-width: 640px;
+  line-height: 28px;
+  font-size: 20px;
+  font-weight: 500;
+  color: var(--c-text-1);
+}
+
 .SContent :deep(p) {
   margin: 0;
+  max-width: 640px;
   line-height: 24px;
   font-size: 14px;
   font-weight: 400;
@@ -36,6 +59,7 @@
 .SContent :deep(ol) {
   margin: 0;
   padding-left: 0;
+  max-width: 640px;
   list-style: none;
 }
 

lib/components/SDivider.vue

@@ -0,0 +1,16 @@
+<template>
+  <div class="SDivider">
+    <div class="line" />
+  </div>
+</template>
+
+<style scoped lang="postcss">
+.SDivider {
+  padding: var(--divider-padding);
+}
+
+.line {
+  height: 1px;
+  background-color: var(--c-divider);
+}
+</style>

lib/components/SDoc.vue

@@ -0,0 +1,17 @@
+<template>
+  <div class="SDoc">
+    <slot />
+  </div>
+</template>
+
+<style scoped lang="postcss">
+.SDoc {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+.SDoc {
+  --divider-padding: 24px 0;
+}
+</style>

lib/components/SDocSection.vue

@@ -0,0 +1,13 @@
+<template>
+  <div class="SDocSection">
+    <slot />
+  </div>
+</template>
+
+<style scoped lang="postcss">
+.SDocSection {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+</style>