react-headings 4.0.0-next.1 → 4.0.0-next.3

package/README.md

@@ -13,12 +13,12 @@
 
 > Never write `h1`–`h6` again.
 
-Search engines and screen readers rely on heading levels, but reusable components can't know how deep they'll be rendered. React Headings works out each level from your component tree, like the HTML [`headingoffset`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/headingoffset) proposal, but in any browser today.
+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
-- 384 bytes minified & brotlied
+- Only 369 bytes minified & brotlied
 - Typed with TypeScript
 - Works with any CSS solution (Tailwind, CSS-in-JS, etc.)
 - Plays nicely with component libraries
@@ -31,37 +31,38 @@ npm install react-headings
 
 ## Usage
 
-Use `H` for every heading. Wrap the content that belongs under a heading in `HeadingLevel`: headings inside render one level deeper.
+Use `Heading` for every heading. Wrap the content that belongs under a heading in `HeadingLevel`: headings inside render one level deeper.
 
 ```tsx
-import { H, HeadingLevel } from "react-headings";
+import { Heading, HeadingLevel } from "react-headings";
 
 function Page() {
   return (
     <>
-      <H>Star Wars</H> {/* h1 */}
+      <Heading>Star Wars</Heading> {/* h1 */}
       <HeadingLevel>
-        <Card title="Characters"> {/* h2 */}
-          <Card title="Luke" /> {/* h3 */}
-          <Card title="Leia" /> {/* h3 */}
-          <Card title="Han Solo" /> {/* h3 */}
-        </Card>
+        <Heading>Characters</Heading> {/* h2 */}
+        <HeadingLevel>
+          <Section title="Luke" /> {/* h3 */}
+          <Section title="Leia" /> {/* h3 */}
+          <Section title="Han Solo" /> {/* h3 */}
+        </HeadingLevel>
       </HeadingLevel>
     </>
   );
 }
 
-function Card({ title, children }) {
+function Section({ title, children }) {
   return (
-    <article>
-      <H>{title}</H>
+    <section>
+      <Heading>{title}</Heading>
       <HeadingLevel>{children}</HeadingLevel>
-    </article>
+    </section>
   );
 }
 ```
 
-`Card` doesn't know its level: it renders `h2` for Characters, `h3` for each character, and `h1` on its own.
+`Section` doesn't know its level: it renders `h3` here.
 
 ### Dialogs
 
@@ -70,7 +71,7 @@ Portaled elements, like dialogs, aren't part of the page outline. Use `level` to
 ```tsx
 <Dialog>
   <HeadingLevel level={1}>
-    <H>Delete file?</H> {/* h1 */}
+    <Heading>Delete file?</Heading> {/* h1 */}
   </HeadingLevel>
 </Dialog>
 ```
@@ -80,14 +81,14 @@ Portaled elements, like dialogs, aren't part of the page outline. Use `level` to
 React Headings only picks the tag. Style headings however you like, or use `render` for your own component:
 
 ```tsx
-<H render={(props, { tag }) => <Text as={tag} size="lg" {...props} />}>
+<Heading render={(props, { tag }) => <Text as={tag} size="lg" {...props} />}>
   Title
-</H>
+</Heading>
 ```
 
 ## API
 
-### `Heading` / `H`
+### `Heading`
 
 Renders `h1`–`h6` based on the current level: `h1` by default, and never deeper than `h6`.
 
@@ -97,8 +98,6 @@ Accepts every `h1` prop and a `ref`, plus:
 | -------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | `render` | `(props, { level, tag }) => ReactElement`    | Renders your own element. Spread `props` on it (includes `children` and `ref`). |
 
-`H` is the same component as `Heading`. Pick one name per project.
-
 ### `HeadingLevel`
 
 | Prop     | Type     | Default | Description                                      |
@@ -108,7 +107,7 @@ Accepts every `h1` prop and a `ref`, plus:
 
 Pass `offset` or `level`, not both. Nested offsets add up. `offset={0}` adds nothing, which is useful for conditional nesting.
 
-Invalid values never throw: fractions round down, and anything else invalid counts as `offset={0}` or `level={1}`.
+Invalid values never throw: they're ignored with a warning, as if not passed. `null` counts as not passed, without a warning.
 
 ### `useHeadingLevel()`
 
@@ -118,22 +117,11 @@ Returns the `level` (`1`–`6`) and `tag` (`"h1"`–`"h6"`) a `Heading` would re
 
 In development, React Headings warns in the console when:
 
-- a level is skipped, like an `h3` with no `h2` above it,
+- a level is skipped,
 - a level goes past 6,
 - an `offset` or `level` is invalid.
 
-Warnings are removed from production builds. Vite and webpack show them automatically in dev mode. In plain Node or Jest, run with `--conditions=development`.
-
-## Server Components
-
-Works in Server Components, including Server Components nested inside `HeadingLevel`. Only `useHeadingLevel()` needs a Client Component.
-
-## Differences from `headingoffset`
-
-- Levels follow the React tree, not the DOM, so portaled content inherits its level.
-- `Heading` always starts at level 1, while a native `h2` starts at 2.
-- Levels stop at 6, while `headingoffset` goes up to 9 through `aria-level`.
-- The output is a real `h1`–`h6` tag, so CSS like `h2 { … }` matches the level.
+Warnings are removed from production builds. Vite and webpack show them automatically in dev mode. In plain Node, run with `--conditions=development`.
 
 ## License
 

package/dist/index.d.ts

@@ -25,7 +25,6 @@ export declare const Heading: import("react").ForwardRefExoticComponent<Omit<imp
         tag: Tag;
     }) => ReactElement;
 } & import("react").RefAttributes<HTMLHeadingElement>>;
-export { Heading as H };
 /**
  * Renders headings inside `offset` levels deeper (default 1), or at `level`
  * regardless of ancestors.
@@ -38,3 +37,4 @@ export declare function useHeadingLevel(): {
     level: Level;
     tag: Tag;
 };
+export {};

package/dist/index.development.js

@@ -10,11 +10,11 @@ import {
 } from "react";
 import { jsx } from "react/jsx-runtime";
 var LevelContext = createContext(1);
-function getNormalizedOffset(offset) {
-  return Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+function isValidOffset(offset) {
+  return Number.isInteger(offset) && offset >= 0;
 }
-function getNormalizedLevel(level) {
-  return Number.isFinite(level) && level > 1 ? Math.floor(level) : 1;
+function isValidLevel(level) {
+  return Number.isInteger(level) && level >= 1;
 }
 var Heading = forwardRef(
   function({ render, ...props }, ref) {
@@ -28,17 +28,13 @@ function HeadingLevel({
   level,
   children
 }) {
-  let parentLevel = useContext(LevelContext), isReset = level !== void 0, normalizedOffset = getNormalizedOffset(offset), innerLevel = isReset ? getNormalizedLevel(level) : parentLevel + normalizedOffset;
-  return useInvalidPropWarning(
-    isReset ? "level" : "offset",
-    isReset ? level : offset,
-    isReset ? innerLevel : normalizedOffset
-  ), children = /* @__PURE__ */ jsx(
+  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 && normalizedOffset === 0,
+      isPassthrough: !isReset && offset === 0,
       children
     }
   ), /* @__PURE__ */ jsx(LevelContext.Provider, { value: innerLevel, children });
@@ -93,15 +89,14 @@ function useHeadingChecks() {
     );
   }, [level]), useEffect(() => scopeRegistry?.register(level), [scopeRegistry, level]);
 }
-function useInvalidPropWarning(prop, value, normalizedValue) {
+function useInvalidPropWarning(prop, value, isValid) {
   useEffect(() => {
-    value !== normalizedValue && console.warn(
-      `react-headings: HeadingLevel received invalid ${prop} ${value}, treated as ${normalizedValue}.`
+    value != null && !isValid && console.warn(
+      `react-headings: HeadingLevel received invalid ${prop} ${value}, ignored.`
     );
-  }, [prop, value, normalizedValue]);
+  }, [prop, value, isValid]);
 }
 export {
-  Heading as H,
   Heading,
   HeadingLevel,
   useHeadingLevel

package/dist/index.js

@@ -10,11 +10,11 @@ import {
 } from "react";
 import { jsx } from "react/jsx-runtime";
 var LevelContext = createContext(1);
-function getNormalizedOffset(offset) {
-  return Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+function isValidOffset(offset) {
+  return Number.isInteger(offset) && offset >= 0;
 }
-function getNormalizedLevel(level) {
-  return Number.isFinite(level) && level > 1 ? Math.floor(level) : 1;
+function isValidLevel(level) {
+  return Number.isInteger(level) && level >= 1;
 }
 var Heading = forwardRef(
   function({ render, ...props }, ref) {
@@ -28,7 +28,7 @@ function HeadingLevel({
   level,
   children
 }) {
-  let parentLevel = useContext(LevelContext), isReset = level !== void 0, normalizedOffset = getNormalizedOffset(offset), innerLevel = isReset ? getNormalizedLevel(level) : parentLevel + normalizedOffset;
+  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 });
 }
 function useHeadingLevel() {
@@ -36,7 +36,6 @@ function useHeadingLevel() {
   return { level, tag: `h${level}` };
 }
 export {
-  Heading as H,
   Heading,
   HeadingLevel,
   useHeadingLevel

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "react-headings",
-  "version": "4.0.0-next.1",
+  "version": "4.0.0-next.3",
   "type": "module",
-  "description": "Dynamic heading levels for React. A polyfill of the HTML headingoffset proposal.",
+  "description": "Dynamic heading levels for React.",
   "author": "Alex Nault",
   "keywords": [
     "react",
     "heading",
     "headings",
-    "headingoffset",
-    "headingreset",
     "level",
     "outline",
     "accessibility",
@@ -20,6 +18,7 @@
   "license": "MIT",
   "repository": "https://github.com/alexnault/react-headings",
   "homepage": "https://github.com/alexnault/react-headings#readme",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",