react-headings 3.3.4 → 3.4.0

package/README.md

@@ -159,6 +159,30 @@ function App() {
 }
 ```
 
+### Dialogs and portals
+
+Content rendered elsewhere in the DOM (e.g. dialogs portalled to the end of `<body>`) can reset the heading hierarchy with the `level` prop.
+Nested sections continue from that level.
+
+```jsx
+import React from "react";
+import { Section, H } from "react-headings";
+
+function App() {
+  return (
+    <Section component={<H>My H1</H>}>
+      <Section component={<H>My H2</H>}>
+        <Dialog>
+          <Section level={1} component={<H>My dialog title (H1)</H>}>
+            My dialog content
+          </Section>
+        </Dialog>
+      </Section>
+    </Section>
+  );
+}
+```
+
 ### Using component libraries
 
 Leveraging `Component` and `level` from the context allows the use of component libraries.
@@ -218,6 +242,7 @@ Creates a new section (a heading and its level).
 | ----------- | ------ | -------- | ------------------------------------------------------------------------------- |
 | `component` | `node` | Yes      | The heading component. Can be anything but best used in combination with `<H>`. |
 | `children`  | `node` | No       | The content of the new level.                                                   |
+| `level`     | `1-6`  | No       | Renders `component` at this level instead of the current one.                   |
 
 #### Example
 

package/dist/index.d.ts

@@ -16,14 +16,26 @@ type HProps = React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>,
  * Renders a dynamic HTML heading (h1, h2, etc.) or custom component according to the current level.
  */
 export declare const H: React.ForwardRefExoticComponent<Omit<HProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+type LevelProps = {
+    level?: Level;
+    children?: React.ReactNode;
+};
+/**
+ * Renders `children` 1 level down, or at `level` when provided.
+ * @param level The level to render `children` at
+ * @param children The children to render
+ */
+declare function Level({ level: desiredLevel, children }: LevelProps): JSX.Element;
 type SectionProps = {
     component: React.ReactNode;
     children?: React.ReactNode;
+    level?: Level;
 };
 /**
  * Renders `component` in the current level and `children` in the next level.
  * @param component A component containing a heading
  * @param children The children in the next level
+ * @param level A level to render `component` at instead of the current one (e.g. for dialogs and portals)
  */
-export declare function Section({ component, children }: SectionProps): JSX.Element;
+export declare function Section({ component, children, level, }: SectionProps): JSX.Element;
 export {};

package/dist/index.js

@@ -38,33 +38,43 @@ function useLevel() {
     return react_1.default.useContext(LevelContext);
 }
 exports.useLevel = useLevel;
-function InternalH(_a, forwardedRef) {
+/**
+ * Renders a dynamic HTML heading (h1, h2, etc.) or custom component according to the current level.
+ */
+exports.H = react_1.default.forwardRef(function H(_a, forwardedRef) {
     var render = _a.render, props = __rest(_a, ["render"]);
     var context = useLevel();
     if (render) {
         return render(context);
     }
     return react_1.default.createElement(context.Component, __assign({ ref: forwardedRef }, props));
-}
+});
 /**
- * Renders a dynamic HTML heading (h1, h2, etc.) or custom component according to the current level.
+ * Renders `children` 1 level down, or at `level` when provided.
+ * @param level The level to render `children` at
+ * @param children The children to render
  */
-exports.H = react_1.default.forwardRef(InternalH);
+function Level(_a) {
+    var desiredLevel = _a.level, children = _a.children;
+    var currentLevel = useLevel().level;
+    var level = desiredLevel !== null && desiredLevel !== void 0 ? desiredLevel : Math.min(currentLevel + 1, 6);
+    var value = {
+        level: level,
+        Component: "h".concat(level),
+    };
+    return (react_1.default.createElement(LevelContext.Provider, { value: value }, children));
+}
 /**
  * Renders `component` in the current level and `children` in the next level.
  * @param component A component containing a heading
  * @param children The children in the next level
+ * @param level A level to render `component` at instead of the current one (e.g. for dialogs and portals)
  */
 function Section(_a) {
-    var component = _a.component, children = _a.children;
-    var level = useLevel().level;
-    var nextLevel = Math.min(level + 1, 6);
-    var value = {
-        level: nextLevel,
-        Component: "h".concat(nextLevel),
-    };
-    return (react_1.default.createElement(react_1.default.Fragment, null,
+    var component = _a.component, children = _a.children, level = _a.level;
+    var content = (react_1.default.createElement(react_1.default.Fragment, null,
         component,
-        react_1.default.createElement(LevelContext.Provider, { value: value }, children)));
+        react_1.default.createElement(Level, null, children)));
+    return level ? react_1.default.createElement(Level, { level: level }, content) : content;
 }
 exports.Section = Section;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-headings",
-  "version": "3.3.4",
+  "version": "3.4.0",
   "description": "HTML headings with auto-incrementing levels for WCAG compliance.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",