react-headings 4.0.0 → 4.0.2

package/README.md

@@ -11,14 +11,14 @@
   </a>
 </p>
 
-> Never write `h1`–`h6` again.
+> Never write `<h1>`–`<h6>` again.
 
 Hardcoded heading levels break accessibility and SEO when components are reused. React Headings fixes this by computing each level from your component tree.
 
 ## Features
 
 - Supports server-side rendering
-- Only 369 bytes minified & brotlied
+- Only 373 bytes minified & brotlied
 - Typed with TypeScript
 - Works with any CSS solution (Tailwind, CSS-in-JS, etc.)
 - Plays nicely with component libraries
@@ -39,13 +39,13 @@ import { Heading, HeadingLevel } from "react-headings";
 function Page() {
   return (
     <>
-      <Heading>Star Wars</Heading> {/* h1 */}
+      <Heading>Star Wars</Heading> {/* <h1> */}
       <HeadingLevel>
-        <Heading>Characters</Heading> {/* h2 */}
+        <Heading>Characters</Heading> {/* <h2> */}
         <HeadingLevel>
-          <Section title="Luke" /> {/* h3 */}
-          <Section title="Leia" /> {/* h3 */}
-          <Section title="Han Solo" /> {/* h3 */}
+          <Section title="Luke" /> {/* <h3> */}
+          <Section title="Leia" /> {/* <h3> */}
+          <Section title="Han Solo" /> {/* <h3> */}
         </HeadingLevel>
       </HeadingLevel>
     </>
@@ -62,23 +62,29 @@ function Section({ title, children }) {
 }
 ```
 
-`Section` doesn't know its level: it renders `h3` here.
+`Section` doesn't know its level: it renders `<h3>` here.
 
 ### Dialogs
 
-Portaled elements, like dialogs, aren't part of the page outline. Use `level` to start their headings at `h1`:
+Portaled elements, like dialogs, aren't part of the page outline. Use `level` to start their headings at `<h1>`:
 
 ```tsx
 <Dialog>
   <HeadingLevel level={1}>
-    <Heading>Delete file?</Heading> {/* h1 */}
+    <Heading>Delete file?</Heading> {/* <h1> */}
   </HeadingLevel>
 </Dialog>
 ```
 
 ### Styling
 
-React Headings only picks the tag. Style headings however you like, or use `render` for your own component:
+React Headings only picks the tag. Style headings however you like:
+
+```tsx
+<Heading className="text-lg">Title</Heading>
+```
+
+Or use `render` for component libraries:
 
 ```tsx
 <Heading render={(props, { tag }) => <Text as={tag} size="lg" {...props} />}>
@@ -88,21 +94,23 @@ React Headings only picks the tag. Style headings however you like, or use `rend
 
 ## API
 
-### `Heading`
+### `<Heading>`
 
-Renders `h1`–`h6` based on the current level: `h1` by default, and never deeper than `h6`.
+Renders `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, or `<h6>` based on the current level. `<h1>` by default.
 
-Accepts every `h1` prop and a `ref`, plus:
+Accepts every `<h1>` prop and a `ref`, plus:
 
 | Prop     | Type                                         | Description                                                                                                 |
 | -------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | `render` | `(props, { level, tag }) => ReactElement`    | Renders your own element. Spread `props` on it (includes `children` and `ref`). |
 
-### `HeadingLevel`
+### `<HeadingLevel>`
+
+Moves the headings inside one level deeper.
 
 | Prop     | Type     | Default | Description                                      |
 | -------- | -------- | ------- | ------------------------------------------------ |
-| `offset` | `number` | `1`     | Levels added to headings inside.                 |
+| `offset` | `number` | `1`     | Levels added to headings inside. Rarely used.    |
 | `level`  | `number` |         | Level of headings inside, ignoring parents.      |
 
 Pass `offset` or `level`, not both. Nested offsets add up. `offset={0}` adds nothing, which is useful for conditional nesting.

package/dist/index.d.ts

@@ -1,40 +1,40 @@
-import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactElement, ReactNode } from "react";
+import { ComponentPropsWithRef, ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 type Level = 1 | 2 | 3 | 4 | 5 | 6;
 type Tag = `h${Level}`;
 export type HeadingProps = ComponentPropsWithoutRef<"h1"> & {
-    render?: (props: ComponentPropsWithRef<"h1">, heading: {
-        level: Level;
-        tag: Tag;
-    }) => ReactElement;
+  render?: (props: ComponentPropsWithRef<"h1">, heading: {
+    level: Level;
+    tag: Tag;
+  }) => ReactElement;
 };
 export type HeadingLevelProps = {
-    children?: ReactNode;
+  children?: ReactNode;
 } & ({
-    offset?: number;
-    level?: never;
+  offset?: number;
+  level?: never;
 } | {
-    level: number;
-    offset?: never;
+  level: number;
+  offset?: never;
 });
 /**
  * Renders an `h1`–`h6` according to the current level.
  */
 export declare const Heading: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, "ref"> & {
-    render?: (props: ComponentPropsWithRef<"h1">, heading: {
-        level: Level;
-        tag: Tag;
-    }) => ReactElement;
+  render?: (props: ComponentPropsWithRef<"h1">, heading: {
+    level: Level;
+    tag: Tag;
+  }) => ReactElement;
 } & import("react").RefAttributes<HTMLHeadingElement>>;
 /**
  * Renders headings inside `offset` levels deeper (default 1), or at `level`
  * regardless of ancestors.
  */
-export declare function HeadingLevel({ offset, level, children, }: HeadingLevelProps): import("react").JSX.Element;
+export declare function HeadingLevel({ offset, level, children }: HeadingLevelProps): import("react").JSX.Element;
 /**
  * Returns the level and tag a `Heading` would render at this position.
  */
 export declare function useHeadingLevel(): {
-    level: Level;
-    tag: Tag;
+  level: Level;
+  tag: Tag;
 };
-export {};
+export {};

package/dist/index.development.js

@@ -1,103 +1,135 @@
 "use client";
-
-// src/index.tsx
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  useEffect,
-  useMemo
-} from "react";
+import { createContext, forwardRef, useContext, useEffect, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
-var LevelContext = createContext(1);
+// src/index.tsx
+const LevelContext = createContext(1);
 function isValidOffset(offset) {
-  return Number.isInteger(offset) && offset >= 0;
+	return Number.isInteger(offset) && offset >= 0;
 }
 function isValidLevel(level) {
-  return Number.isInteger(level) && level >= 1;
+	return Number.isInteger(level) && level >= 1;
 }
-var Heading = forwardRef(
-  function({ render, ...props }, ref) {
-    let { level, tag } = useHeadingLevel();
-    return useHeadingChecks(), render ? render({ ...props, ref }, { level, tag }) : /* @__PURE__ */ jsx(tag, { ref, ...props });
-  }
-);
+/**
+* Renders an `h1`–`h6` according to the current level.
+*/
+const Heading = forwardRef(function Heading({ render, ...props }, ref) {
+	const { level, tag } = useHeadingLevel();
+	useHeadingChecks();
+	if (render) return render({
+		...props,
+		ref
+	}, {
+		level,
+		tag
+	});
+	return /* @__PURE__ */ jsx(tag, {
+		ref,
+		...props
+	});
+});
 Heading.displayName = "Heading";
-function HeadingLevel({
-  offset = 1,
-  level,
-  children
-}) {
-  let parentLevel = useContext(LevelContext), isReset = isValidLevel(level), isOffsetValid = isValidOffset(offset), innerLevel = isReset ? level : parentLevel + (isOffsetValid ? offset : 1);
-  return useInvalidPropWarning("offset", offset, isOffsetValid), useInvalidPropWarning("level", level, isReset), children = /* @__PURE__ */ jsx(
-    SkippedLevelScope,
-    {
-      firstLevel: isReset ? innerLevel : parentLevel + 1,
-      isIsolated: isReset,
-      isPassthrough: !isReset && offset === 0,
-      children
-    }
-  ), /* @__PURE__ */ jsx(LevelContext.Provider, { value: innerLevel, children });
+/**
+* Renders headings inside `offset` levels deeper (default 1), or at `level`
+* regardless of ancestors.
+*/
+function HeadingLevel({ offset = 1, level, children }) {
+	const parentLevel = useContext(LevelContext);
+	const isReset = isValidLevel(level);
+	const isOffsetValid = isValidOffset(offset);
+	const innerLevel = isReset ? level : parentLevel + (isOffsetValid ? offset : 1);
+	useInvalidPropWarning("offset", offset, isOffsetValid);
+	useInvalidPropWarning("level", level, isReset);
+	children = /* @__PURE__ */ jsx(SkippedLevelScope, {
+		firstLevel: isReset ? innerLevel : parentLevel + 1,
+		isIsolated: isReset,
+		isPassthrough: !isReset && offset === 0,
+		children
+	});
+	return /* @__PURE__ */ jsx(LevelContext.Provider, {
+		value: innerLevel,
+		children
+	});
 }
+/**
+* Returns the level and tag a `Heading` would render at this position.
+*/
 function useHeadingLevel() {
-  let level = Math.min(useContext(LevelContext), 6);
-  return { level, tag: `h${level}` };
+	const level = Math.min(useContext(LevelContext), 6);
+	return {
+		level,
+		tag: `h${level}`
+	};
 }
-var ScopeContext = /* @__PURE__ */ createContext(null);
+const ScopeContext = /* @__PURE__ */ createContext(null);
+/**
+* Collects the heading levels rendered inside a HeadingLevel and warns if one between `firstLevel` and the deepest is missing. A
+* non-empty nested scope counts as a heading at its own `firstLevel` in its
+* parent, so each gap is reported by exactly one scope.
+*/
 function createScopeRegistry(firstLevel, parentRegistry) {
-  let headingLevels = /* @__PURE__ */ new Map(), unregisterFromParent, isCheckScheduled = !1, hasWarned = !1;
-  function warnIfLevelSkipped() {
-    if (isCheckScheduled = !1, hasWarned || headingLevels.size === 0) return;
-    let presentLevels = new Set(headingLevels.values()), deepestLevel = Math.max(...presentLevels);
-    for (let level = firstLevel; level < deepestLevel; level++)
-      if (!presentLevels.has(level)) {
-        hasWarned = !0, console.warn(
-          `react-headings: Skipped heading level ${level}: found a level ${deepestLevel} heading but no level ${level} heading.`
-        );
-        return;
-      }
-  }
-  function scheduleCheck() {
-    isCheckScheduled || (isCheckScheduled = !0, queueMicrotask(warnIfLevelSkipped));
-  }
-  return {
-    register(level) {
-      let token = {};
-      return headingLevels.set(token, level), headingLevels.size === 1 && (unregisterFromParent = parentRegistry?.register(firstLevel)), scheduleCheck(), () => {
-        headingLevels.delete(token), headingLevels.size === 0 && (unregisterFromParent?.(), unregisterFromParent = void 0), scheduleCheck();
-      };
-    }
-  };
+	const headingLevels = /* @__PURE__ */ new Map();
+	let unregisterFromParent;
+	let isCheckScheduled = false;
+	let hasWarned = false;
+	function warnIfLevelSkipped() {
+		isCheckScheduled = false;
+		if (hasWarned || headingLevels.size === 0) return;
+		const presentLevels = new Set(headingLevels.values());
+		const deepestLevel = Math.max(...presentLevels);
+		for (let level = firstLevel; level < deepestLevel; level++) if (!presentLevels.has(level)) {
+			hasWarned = true;
+			console.warn(`react-headings: Skipped heading level ${level}: found a level ${deepestLevel} heading but no level ${level} heading.`);
+			return;
+		}
+	}
+	function scheduleCheck() {
+		if (isCheckScheduled) return;
+		isCheckScheduled = true;
+		queueMicrotask(warnIfLevelSkipped);
+	}
+	return { register(level) {
+		const token = {};
+		headingLevels.set(token, level);
+		if (headingLevels.size === 1) unregisterFromParent = parentRegistry?.register(firstLevel);
+		scheduleCheck();
+		return () => {
+			headingLevels.delete(token);
+			if (headingLevels.size === 0) {
+				unregisterFromParent?.();
+				unregisterFromParent = void 0;
+			}
+			scheduleCheck();
+		};
+	} };
 }
-function SkippedLevelScope({
-  firstLevel,
-  isIsolated,
-  isPassthrough,
-  children
-}) {
-  let parentRegistry = useContext(ScopeContext), registry = useMemo(
-    () => isPassthrough ? parentRegistry : createScopeRegistry(firstLevel, isIsolated ? null : parentRegistry),
-    [firstLevel, isIsolated, isPassthrough, parentRegistry]
-  );
-  return /* @__PURE__ */ jsx(ScopeContext.Provider, { value: registry, children });
+function SkippedLevelScope({ firstLevel, isIsolated, isPassthrough, children }) {
+	const parentRegistry = useContext(ScopeContext);
+	const registry = useMemo(() => isPassthrough ? parentRegistry : createScopeRegistry(firstLevel, isIsolated ? null : parentRegistry), [
+		firstLevel,
+		isIsolated,
+		isPassthrough,
+		parentRegistry
+	]);
+	return /* @__PURE__ */ jsx(ScopeContext.Provider, {
+		value: registry,
+		children
+	});
 }
 function useHeadingChecks() {
-  let level = useContext(LevelContext), scopeRegistry = useContext(ScopeContext);
-  useEffect(() => {
-    level > 6 && console.warn(
-      `react-headings: Heading level ${level} exceeds 6 and was clamped to h6.`
-    );
-  }, [level]), useEffect(() => scopeRegistry?.register(level), [scopeRegistry, level]);
+	const level = useContext(LevelContext);
+	const scopeRegistry = useContext(ScopeContext);
+	useEffect(() => {
+		if (level > 6) console.warn(`react-headings: Heading level ${level} exceeds 6 and was clamped to h6.`);
+	}, [level]);
+	useEffect(() => scopeRegistry?.register(level), [scopeRegistry, level]);
 }
 function useInvalidPropWarning(prop, value, isValid) {
-  useEffect(() => {
-    value != null && !isValid && console.warn(
-      `react-headings: HeadingLevel received invalid ${prop} ${value}, ignored.`
-    );
-  }, [prop, value, isValid]);
+	useEffect(() => {
+		if (value != null && !isValid) console.warn(`react-headings: HeadingLevel received invalid ${prop} ${value}, ignored.`);
+	}, [
+		prop,
+		value,
+		isValid
+	]);
 }
-export {
-  Heading,
-  HeadingLevel,
-  useHeadingLevel
-};
+export { Heading, HeadingLevel, useHeadingLevel };

package/dist/index.js

@@ -1,42 +1,54 @@
 "use client";
-
-// src/index.tsx
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  useEffect,
-  useMemo
-} from "react";
+import { createContext, forwardRef, useContext } from "react";
 import { jsx } from "react/jsx-runtime";
-var LevelContext = createContext(1);
+// src/index.tsx
+const LevelContext = createContext(1);
 function isValidOffset(offset) {
-  return Number.isInteger(offset) && offset >= 0;
+	return Number.isInteger(offset) && offset >= 0;
 }
 function isValidLevel(level) {
-  return Number.isInteger(level) && level >= 1;
+	return Number.isInteger(level) && level >= 1;
 }
-var Heading = forwardRef(
-  function({ render, ...props }, ref) {
-    let { level, tag } = useHeadingLevel();
-    return render ? render({ ...props, ref }, { level, tag }) : /* @__PURE__ */ jsx(tag, { ref, ...props });
-  }
-);
+/**
+* Renders an `h1`–`h6` according to the current level.
+*/
+const Heading = forwardRef(function Heading({ render, ...props }, ref) {
+	const { level, tag } = useHeadingLevel();
+	if (render) return render({
+		...props,
+		ref
+	}, {
+		level,
+		tag
+	});
+	return /* @__PURE__ */ jsx(tag, {
+		ref,
+		...props
+	});
+});
 Heading.displayName = "Heading";
-function HeadingLevel({
-  offset = 1,
-  level,
-  children
-}) {
-  let parentLevel = useContext(LevelContext), isReset = isValidLevel(level), isOffsetValid = isValidOffset(offset), innerLevel = isReset ? level : parentLevel + (isOffsetValid ? offset : 1);
-  return /* @__PURE__ */ jsx(LevelContext.Provider, { value: innerLevel, children });
+/**
+* Renders headings inside `offset` levels deeper (default 1), or at `level`
+* regardless of ancestors.
+*/
+function HeadingLevel({ offset = 1, level, children }) {
+	const parentLevel = useContext(LevelContext);
+	const isReset = isValidLevel(level);
+	const isOffsetValid = isValidOffset(offset);
+	const innerLevel = isReset ? level : parentLevel + (isOffsetValid ? offset : 1);
+	return /* @__PURE__ */ jsx(LevelContext.Provider, {
+		value: innerLevel,
+		children
+	});
 }
+/**
+* Returns the level and tag a `Heading` would render at this position.
+*/
 function useHeadingLevel() {
-  let level = Math.min(useContext(LevelContext), 6);
-  return { level, tag: `h${level}` };
+	const level = Math.min(useContext(LevelContext), 6);
+	return {
+		level,
+		tag: `h${level}`
+	};
 }
-export {
-  Heading,
-  HeadingLevel,
-  useHeadingLevel
-};
+export { Heading, HeadingLevel, useHeadingLevel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-headings",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "type": "module",
   "description": "Dynamic heading levels for React.",
   "author": "Alex Nault",
@@ -29,7 +29,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "rm -rf dist && node scripts/build.js && tsc -p tsconfig.build.json",
+    "build": "tsdown",
     "typecheck": "tsc",
     "format": "prettier ./ --write",
     "lint": "eslint ./ --max-warnings=0",
@@ -48,21 +48,22 @@
     "@size-limit/preset-small-lib": "^14.3.0",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",
+    "@types/node": "^24.19.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@vitest/coverage-v8": "^5.0.5",
+    "@vitest/coverage-v8": "^5.1.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
-    "esbuild": "^0.28.2",
     "eslint": "^10.14.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^30.1.3",
     "prettier": "^3.9.10",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
-    "semantic-release": "^25.0.3",
+    "semantic-release": "^25.0.9",
     "size-limit": "^14.3.0",
-    "typescript": "^5.9.3",
+    "tsdown": "^0.23.5",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.72.1",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   }
 }