feat(heading): add Heading and Section components (#1961)

COMPONENT_INDEX.md

@@ -1,6 +1,6 @@
 # Component Index
 
-> 166 components exported from carbon-components-svelte@1.0.0-next.1.
+> 168 components exported from carbon-components-svelte@1.0.0-next.1.
 
 ## Components
 
@@ -63,6 +63,7 @@
 - [`HeaderPanelLinks`](#headerpanellinks)
 - [`HeaderSearch`](#headersearch)
 - [`HeaderUtilities`](#headerutilities)
+- [`Heading`](#heading)
 - [`ImageLoader`](#imageloader)
 - [`InlineLoading`](#inlineloading)
 - [`InlineNotification`](#inlinenotification)
@@ -109,6 +110,7 @@
 - [`Row`](#row)
 - [`Search`](#search)
 - [`SearchSkeleton`](#searchskeleton)
+- [`Section`](#section)
 - [`Select`](#select)
 - [`SelectItem`](#selectitem)
 - [`SelectItemGroup`](#selectitemgroup)
@@ -1852,6 +1854,28 @@ None.
 
 None.
 
+## `Heading`
+
+### Types
+
+```ts
+export type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
+```
+
+### Props
+
+None.
+
+### Slots
+
+| Slot name | Default | Props | Fallback |
+| :-------- | :------ | :---- | :------- |
+| --        | Yes     | --    | --       |
+
+### Events
+
+None.
+
 ## `ImageLoader`
 
 ### Props
@@ -3177,6 +3201,31 @@ None.
 | mouseenter | forwarded | --     |
 | mouseleave | forwarded | --     |
 
+## `Section`
+
+### Types
+
+```ts
+export type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
+```
+
+### Props
+
+| Prop name | Required | Kind             | Reactive | Type                                     | Default value          | Description                                    |
+| :-------- | :------- | :--------------- | :------- | ---------------------------------------- | ---------------------- | ---------------------------------------------- |
+| level     | No       | <code>let</code> | No       | <code>SectionLevel</code>                | <code>1</code>         | Specify the level the section should start at. |
+| tag       | No       | <code>let</code> | No       | <code>keyof HTMLElementTagNameMap</code> | <code>"section"</code> | Specify the tag name                           |
+
+### Slots
+
+| Slot name | Default | Props | Fallback |
+| :-------- | :------ | :---- | :------- |
+| --        | Yes     | --    | --       |
+
+### Events
+
+None.
+
 ## `Select`
 
 ### Props

docs/src/COMPONENT_API.json

@@ -1,5 +1,5 @@
 {
-  "total": 166,
+  "total": 168,
   "components": [
     {
       "moduleName": "Accordion",
@@ -5386,6 +5386,21 @@
       "events": [],
       "typedefs": []
     },
+    {
+      "moduleName": "Heading",
+      "filePath": "src/Heading/Heading.svelte",
+      "props": [],
+      "moduleExports": [],
+      "slots": [{ "name": "__default__", "default": true, "slot_props": "{}" }],
+      "events": [],
+      "typedefs": [
+        {
+          "type": "1 | 2 | 3 | 4 | 5 | 6",
+          "name": "SectionLevel",
+          "ts": "type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6"
+        }
+      ]
+    },
     {
       "moduleName": "ImageLoader",
       "filePath": "src/ImageLoader/ImageLoader.svelte",
@@ -10181,6 +10196,46 @@
       "typedefs": [],
       "rest_props": { "type": "Element", "name": "div" }
     },
+    {
+      "moduleName": "Section",
+      "filePath": "src/Heading/Section.svelte",
+      "props": [
+        {
+          "name": "level",
+          "kind": "let",
+          "description": "Specify the level the section should start at.",
+          "type": "SectionLevel",
+          "value": "1",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "tag",
+          "kind": "let",
+          "description": "Specify the tag name",
+          "type": "keyof HTMLElementTagNameMap",
+          "value": "\"section\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        }
+      ],
+      "moduleExports": [],
+      "slots": [{ "name": "__default__", "default": true, "slot_props": "{}" }],
+      "events": [],
+      "typedefs": [
+        {
+          "type": "1 | 2 | 3 | 4 | 5 | 6",
+          "name": "SectionLevel",
+          "ts": "type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6"
+        }
+      ]
+    },
     {
       "moduleName": "Select",
       "filePath": "src/Select/Select.svelte",

docs/src/pages/components/Heading.svx

@@ -0,0 +1,72 @@
+---
+components: ["Heading", "Section"]
+---
+
+<script>
+  import { Heading, Section } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+The `Heading` component automatically adjusts the level of the heading based on the nesting level of the `Section` component.
+
+## Default
+
+For example, the top-level `Heading` inside a `Section` will be rendered as a semantic `h1` element.
+
+<Section>
+  <Heading>Heading 1</Heading>
+</Section>
+
+## Nested sections
+
+Section headings are capped at `h6`.
+
+<Section>
+  <Heading>Heading 1</Heading>
+  <Section>
+    <Heading>Heading 2</Heading>
+    <Section>
+      <Heading>Heading 3</Heading>
+      <Section>
+        <Heading>Heading 4</Heading>
+        <Section>
+          <Heading>Heading 5</Heading>
+          <Section>
+            <Heading>Heading 6</Heading>
+            <Section>
+              <Heading>Capped at Heading 6</Heading>
+            </Section>
+          </Section>
+        </Section>
+      </Section>
+    </Section>
+  </Section>
+  <Section>
+    <Heading>Heading 2</Heading>
+  </Section>
+</Section>
+
+
+## Custom level
+
+To specify a custom start level, use the `level` prop.
+
+<Section level={5}>
+  <Heading>Starts at Heading 5</Heading>
+  <Section>
+    <Heading>Heading 6</Heading>
+    <Section>
+      <Heading>Capped at Heading 6</Heading>
+    </Section>
+  </Section>
+</Section>
+
+## Custom section element
+
+The `Section` component renders a `section` by default.
+
+Use the `tag` prop to render a different element.
+ 
+<Section tag="div">
+  <Heading>Heading 1</Heading>
+</Section>

src/Heading/Heading.svelte

@@ -0,0 +1,18 @@
+<script>
+  // @ts-check
+
+  /**
+   * @typedef {1 | 2 | 3 | 4 | 5 | 6} SectionLevel
+   */
+
+  import { getContext } from "svelte";
+
+  /** @type {undefined | SectionLevel} */
+  const sectionLevel = getContext("Section");
+
+  $: tag = `h${sectionLevel ?? 1}`;
+</script>
+
+<svelte:element this="{tag}">
+  <slot />
+</svelte:element>

src/Heading/Section.svelte

@@ -0,0 +1,42 @@
+<script>
+  // @ts-check
+
+  /**
+   * @typedef {1 | 2 | 3 | 4 | 5 | 6} SectionLevel
+   */
+
+  /**
+   * Specify the level the section should start at.
+   * @type {SectionLevel}
+   */
+  export let level = 1;
+
+  /**
+   * Specify the tag name
+   * @type {keyof HTMLElementTagNameMap}
+   */
+  export let tag = "section";
+
+  import { getContext, setContext } from "svelte";
+  import { writable } from "svelte/store";
+
+  /** @type {undefined | SectionLevel} */
+  const parentLevel = getContext("Section");
+
+  /** @type {import ("svelte/store").Writable<SectionLevel>} */
+  const internalLevel = writable(level);
+
+  if (typeof parentLevel === "number") {
+    // @ts-expect-error
+    internalLevel.set(Math.min(parentLevel + 1, 6));
+  }
+
+  // Custom level should override the inferred parent level.
+  if (level !== 1) {
+    internalLevel.set(level);
+  }
+
+  setContext("Section", $internalLevel);
+</script>
+
+<svelte:element this="{tag}"><slot /></svelte:element>

src/Heading/index.js

@@ -0,0 +1,2 @@
+export { default as Heading } from "./Heading.svelte";
+export { default as Section } from "./Section.svelte";

src/index.js

@@ -56,6 +56,7 @@ export { FormGroup } from "./FormGroup";
 export { FormItem } from "./FormItem";
 export { FormLabel } from "./FormLabel";
 export { Grid, Row, Column } from "./Grid";
+export { Heading, Section } from "./Heading";
 export { ImageLoader } from "./ImageLoader";
 export { InlineLoading } from "./InlineLoading";
 export { Layer } from "./Layer";

tests/Heading.test.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import { Heading, Section } from "../types";
+</script>
+
+<Section tag="div">
+  <Heading>Heading 1</Heading>
+  <Section level="{5}">
+    <Heading>Starts at Heading 5</Heading>
+  </Section>
+</Section>

types/Heading/Heading.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { SvelteComponentTyped } from "svelte";
+
+export type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface HeadingProps {}
+
+export default class Heading extends SvelteComponentTyped<
+  HeadingProps,
+  Record<string, any>,
+  { default: {} }
+> {}

types/Heading/Section.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { SvelteComponentTyped } from "svelte";
+
+export type SectionLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface SectionProps {
+  /**
+   * Specify the level the section should start at.
+   * @default 1
+   */
+  level?: SectionLevel;
+
+  /**
+   * Specify the tag name
+   * @default "section"
+   */
+  tag?: keyof HTMLElementTagNameMap;
+}
+
+export default class Section extends SvelteComponentTyped<
+  SectionProps,
+  Record<string, any>,
+  { default: {} }
+> {}

types/index.d.ts

@@ -62,6 +62,8 @@ export { default as FormLabel } from "./FormLabel/FormLabel.svelte";
 export { default as Grid } from "./Grid/Grid.svelte";
 export { default as Row } from "./Grid/Row.svelte";
 export { default as Column } from "./Grid/Column.svelte";
+export { default as Heading } from "./Heading/Heading.svelte";
+export { default as Section } from "./Heading/Section.svelte";
 export { default as ImageLoader } from "./ImageLoader/ImageLoader.svelte";
 export { default as InlineLoading } from "./InlineLoading/InlineLoading.svelte";
 export { default as Layer } from "./Layer/Layer.svelte";