react-headings 3.3.3 → 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

@@ -1,7 +1,7 @@
 import React from "react";
-declare type Level = 1 | 2 | 3 | 4 | 5 | 6;
-declare type Heading = `h${Level}`;
-declare type LevelContextValue = {
+type Level = 1 | 2 | 3 | 4 | 5 | 6;
+type Heading = `h${Level}`;
+type LevelContextValue = {
     level: Level;
     Component: Heading;
 };
@@ -9,21 +9,33 @@ declare type LevelContextValue = {
  * Returns the current heading and level.
  */
 export declare function useLevel(): LevelContextValue;
-declare type HProps = React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement> & {
+type HProps = React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement> & {
     render?: (context: LevelContextValue) => React.ReactElement;
 };
 /**
  * Renders a dynamic HTML heading (h1, h2, etc.) or custom component according to the current level.
  */
-export declare const H: React.ForwardRefExoticComponent<Pick<HProps, "render" | "key" | keyof React.HTMLAttributes<HTMLHeadingElement>> & React.RefAttributes<HTMLHeadingElement>>;
-declare type SectionProps = {
+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" + 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.3",
+  "version": "3.4.0",
   "description": "HTML headings with auto-incrementing levels for WCAG compliance.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,22 +36,22 @@
   },
   "devDependencies": {
     "@size-limit/preset-small-lib": "^7.0.8",
-    "@testing-library/react": "^13.0.1",
-    "@types/react": "^18.0.3",
-    "@types/react-dom": "^18.0.0",
+    "@testing-library/react": "^13.4.0",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
     "@typescript-eslint/eslint-plugin": "^4.33.0",
     "@typescript-eslint/parser": "^4.33.0",
     "@vitest/coverage-c8": "^0.30.1",
-    "conventional-changelog-conventionalcommits": "^4.6.1",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
     "eslint": "^7.32.0",
-    "eslint-config-prettier": "^8.3.0",
-    "jsdom": "^21.1.1",
-    "prettier": "^2.7.1",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "semantic-release": "^21.0.1",
+    "eslint-config-prettier": "^8.10.2",
+    "jsdom": "^21.1.2",
+    "prettier": "^2.8.8",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "semantic-release": "^25.0.3",
     "size-limit": "^7.0.8",
-    "typescript": "^4.4.3",
+    "typescript": "^4.9.5",
     "vitest": "^0.30.1"
   }
 }