@capra/core 1.5.2 → 1.6.0

package/dist/index.cjs

@@ -270,12 +270,12 @@ Label$1.displayName = "Label";
 //#endregion
 //#region src/components/TextInput/TextInput.module.css
 var TextInput_module_default = {
-	"errorIndicator": "capra-TextInput-module-I5TDpa-errorIndicator",
-	"input": "capra-TextInput-module-I5TDpa-input",
-	"leadingSlot": "capra-TextInput-module-I5TDpa-leadingSlot",
-	"trailingSlot": "capra-TextInput-module-I5TDpa-trailingSlot",
-	"warningIndicator": "capra-TextInput-module-I5TDpa-warningIndicator",
-	"wrapper": "capra-TextInput-module-I5TDpa-wrapper"
+	"errorIndicator": "capra-TextInput-module-pTHfnG-errorIndicator",
+	"input": "capra-TextInput-module-pTHfnG-input",
+	"leadingSlot": "capra-TextInput-module-pTHfnG-leadingSlot",
+	"trailingSlot": "capra-TextInput-module-pTHfnG-trailingSlot",
+	"warningIndicator": "capra-TextInput-module-pTHfnG-warningIndicator",
+	"wrapper": "capra-TextInput-module-pTHfnG-wrapper"
 };
 //#endregion
 //#region src/components/TextInput/TextInput.tsx
@@ -2733,23 +2733,23 @@ TextArea.displayName = "TextArea";
 //#endregion
 //#region src/components/Modal/Modal.module.css
 var Modal_module_default = {
-	"confirmationActions": "capra-Modal-module-5vfSOW-confirmationActions",
-	"confirmationBody": "capra-Modal-module-5vfSOW-confirmationBody",
-	"confirmationIcon": "capra-Modal-module-5vfSOW-confirmationIcon",
-	"confirmationLayout": "capra-Modal-module-5vfSOW-confirmationLayout",
-	"confirmationMessage": "capra-Modal-module-5vfSOW-confirmationMessage",
-	"confirmationSurface": "capra-Modal-module-5vfSOW-confirmationSurface",
-	"content": "capra-Modal-module-5vfSOW-content",
-	"contentShow": "capra-Modal-module-5vfSOW-contentShow",
-	"expandedFooterLayout": "capra-Modal-module-5vfSOW-expandedFooterLayout",
-	"expandedTitleLayout": "capra-Modal-module-5vfSOW-expandedTitleLayout",
-	"footer": "capra-Modal-module-5vfSOW-footer",
-	"footerActions": "capra-Modal-module-5vfSOW-footerActions",
-	"header": "capra-Modal-module-5vfSOW-header",
-	"headerLeading": "capra-Modal-module-5vfSOW-headerLeading",
-	"overlay": "capra-Modal-module-5vfSOW-overlay",
-	"overlayShow": "capra-Modal-module-5vfSOW-overlayShow",
-	"surface": "capra-Modal-module-5vfSOW-surface"
+	"confirmationActions": "capra-Modal-module-j-u8iq-confirmationActions",
+	"confirmationBody": "capra-Modal-module-j-u8iq-confirmationBody",
+	"confirmationIcon": "capra-Modal-module-j-u8iq-confirmationIcon",
+	"confirmationLayout": "capra-Modal-module-j-u8iq-confirmationLayout",
+	"confirmationMessage": "capra-Modal-module-j-u8iq-confirmationMessage",
+	"confirmationSurface": "capra-Modal-module-j-u8iq-confirmationSurface",
+	"content": "capra-Modal-module-j-u8iq-content",
+	"contentShow": "capra-Modal-module-j-u8iq-contentShow",
+	"expandedFooterLayout": "capra-Modal-module-j-u8iq-expandedFooterLayout",
+	"expandedTitleLayout": "capra-Modal-module-j-u8iq-expandedTitleLayout",
+	"footer": "capra-Modal-module-j-u8iq-footer",
+	"footerActions": "capra-Modal-module-j-u8iq-footerActions",
+	"header": "capra-Modal-module-j-u8iq-header",
+	"headerLeading": "capra-Modal-module-j-u8iq-headerLeading",
+	"overlay": "capra-Modal-module-j-u8iq-overlay",
+	"overlayShow": "capra-Modal-module-j-u8iq-overlayShow",
+	"surface": "capra-Modal-module-j-u8iq-surface"
 };
 //#endregion
 //#region src/components/Text/Heading.tsx
@@ -3427,9 +3427,12 @@ var EmptyState_module_default = {
 };
 //#endregion
 //#region src/components/EmptyState/EmptyState.tsx
+const NOOP_IMAGE = () => null;
 function lazyLoad(importFn) {
 	return react.default.lazy(() => importFn().then((m) => {
-		return { default: m[Object.getOwnPropertyNames(m)[0]] };
+		const componentName = Object.getOwnPropertyNames(m).find((name) => name.match(/^[A-Z]/));
+		if (!componentName) return { default: NOOP_IMAGE };
+		return { default: m[componentName] };
 	}));
 }
 const ILLUSTRATIONS = {

package/dist/index.mjs

@@ -246,12 +246,12 @@ Label$1.displayName = "Label";
 //#endregion
 //#region src/components/TextInput/TextInput.module.css
 var TextInput_module_default = {
-	"errorIndicator": "capra-TextInput-module-I5TDpa-errorIndicator",
-	"input": "capra-TextInput-module-I5TDpa-input",
-	"leadingSlot": "capra-TextInput-module-I5TDpa-leadingSlot",
-	"trailingSlot": "capra-TextInput-module-I5TDpa-trailingSlot",
-	"warningIndicator": "capra-TextInput-module-I5TDpa-warningIndicator",
-	"wrapper": "capra-TextInput-module-I5TDpa-wrapper"
+	"errorIndicator": "capra-TextInput-module-pTHfnG-errorIndicator",
+	"input": "capra-TextInput-module-pTHfnG-input",
+	"leadingSlot": "capra-TextInput-module-pTHfnG-leadingSlot",
+	"trailingSlot": "capra-TextInput-module-pTHfnG-trailingSlot",
+	"warningIndicator": "capra-TextInput-module-pTHfnG-warningIndicator",
+	"wrapper": "capra-TextInput-module-pTHfnG-wrapper"
 };
 //#endregion
 //#region src/components/TextInput/TextInput.tsx
@@ -2709,23 +2709,23 @@ TextArea.displayName = "TextArea";
 //#endregion
 //#region src/components/Modal/Modal.module.css
 var Modal_module_default = {
-	"confirmationActions": "capra-Modal-module-5vfSOW-confirmationActions",
-	"confirmationBody": "capra-Modal-module-5vfSOW-confirmationBody",
-	"confirmationIcon": "capra-Modal-module-5vfSOW-confirmationIcon",
-	"confirmationLayout": "capra-Modal-module-5vfSOW-confirmationLayout",
-	"confirmationMessage": "capra-Modal-module-5vfSOW-confirmationMessage",
-	"confirmationSurface": "capra-Modal-module-5vfSOW-confirmationSurface",
-	"content": "capra-Modal-module-5vfSOW-content",
-	"contentShow": "capra-Modal-module-5vfSOW-contentShow",
-	"expandedFooterLayout": "capra-Modal-module-5vfSOW-expandedFooterLayout",
-	"expandedTitleLayout": "capra-Modal-module-5vfSOW-expandedTitleLayout",
-	"footer": "capra-Modal-module-5vfSOW-footer",
-	"footerActions": "capra-Modal-module-5vfSOW-footerActions",
-	"header": "capra-Modal-module-5vfSOW-header",
-	"headerLeading": "capra-Modal-module-5vfSOW-headerLeading",
-	"overlay": "capra-Modal-module-5vfSOW-overlay",
-	"overlayShow": "capra-Modal-module-5vfSOW-overlayShow",
-	"surface": "capra-Modal-module-5vfSOW-surface"
+	"confirmationActions": "capra-Modal-module-j-u8iq-confirmationActions",
+	"confirmationBody": "capra-Modal-module-j-u8iq-confirmationBody",
+	"confirmationIcon": "capra-Modal-module-j-u8iq-confirmationIcon",
+	"confirmationLayout": "capra-Modal-module-j-u8iq-confirmationLayout",
+	"confirmationMessage": "capra-Modal-module-j-u8iq-confirmationMessage",
+	"confirmationSurface": "capra-Modal-module-j-u8iq-confirmationSurface",
+	"content": "capra-Modal-module-j-u8iq-content",
+	"contentShow": "capra-Modal-module-j-u8iq-contentShow",
+	"expandedFooterLayout": "capra-Modal-module-j-u8iq-expandedFooterLayout",
+	"expandedTitleLayout": "capra-Modal-module-j-u8iq-expandedTitleLayout",
+	"footer": "capra-Modal-module-j-u8iq-footer",
+	"footerActions": "capra-Modal-module-j-u8iq-footerActions",
+	"header": "capra-Modal-module-j-u8iq-header",
+	"headerLeading": "capra-Modal-module-j-u8iq-headerLeading",
+	"overlay": "capra-Modal-module-j-u8iq-overlay",
+	"overlayShow": "capra-Modal-module-j-u8iq-overlayShow",
+	"surface": "capra-Modal-module-j-u8iq-surface"
 };
 //#endregion
 //#region src/components/Text/Heading.tsx
@@ -3403,9 +3403,12 @@ var EmptyState_module_default = {
 };
 //#endregion
 //#region src/components/EmptyState/EmptyState.tsx
+const NOOP_IMAGE = () => null;
 function lazyLoad(importFn) {
 	return React.lazy(() => importFn().then((m) => {
-		return { default: m[Object.getOwnPropertyNames(m)[0]] };
+		const componentName = Object.getOwnPropertyNames(m).find((name) => name.match(/^[A-Z]/));
+		if (!componentName) return { default: NOOP_IMAGE };
+		return { default: m[componentName] };
 	}));
 }
 const ILLUSTRATIONS = {

package/dist/style.css

@@ -342,7 +342,7 @@
   position: absolute;
   overflow: hidden;
 }
-.capra-TextInput-module-I5TDpa-wrapper {
+.capra-TextInput-module-pTHfnG-wrapper {
   border: var(--cds2-border-default);
   border-color: var(--cds2-temporary-input-border-primary);
   border-radius: var(--cds2-radius-md);
@@ -371,7 +371,7 @@
     border-color: var(--cds2-temporary-input-border-disabled);
     color: var(--cds2-temporary-input-foreground-disabled);
 
-    & .capra-TextInput-module-I5TDpa-leadingSlot, & .capra-TextInput-module-I5TDpa-trailingSlot {
+    & .capra-TextInput-module-pTHfnG-leadingSlot, & .capra-TextInput-module-pTHfnG-trailingSlot {
       color: var(--cds2-temporary-input-foreground-disabled);
     }
   }
@@ -379,7 +379,7 @@
   &:has( > input:read-only) {
     cursor: default;
 
-    & .capra-TextInput-module-I5TDpa-input {
+    & .capra-TextInput-module-pTHfnG-input {
       cursor: default;
     }
   }
@@ -387,12 +387,12 @@
   &:has( > input:disabled) {
     cursor: not-allowed;
 
-    & .capra-TextInput-module-I5TDpa-input {
+    & .capra-TextInput-module-pTHfnG-input {
       cursor: not-allowed;
     }
   }
 
-  & .capra-TextInput-module-I5TDpa-input {
+  & .capra-TextInput-module-pTHfnG-input {
     min-width: 0;
     color: inherit;
     font: inherit;
@@ -408,26 +408,56 @@
   }
 
   &[data-size="sm"] {
-    padding-inline: var(--cds2-spacing-md);
     gap: var(--cds2-spacing-sm);
 
-    & .capra-TextInput-module-I5TDpa-input {
+    &:not(:has(.capra-TextInput-module-pTHfnG-leadingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    &:not(:has(.capra-TextInput-module-pTHfnG-trailingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-input {
       height: calc(var(--cds2-dimension-component-sm) - 2px);
       font: var(--cds2-typography-body-sm-normal);
     }
+
+    & .capra-TextInput-module-pTHfnG-leadingSlot {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-trailingSlot {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
   }
 
   &[data-size="md"] {
-    padding-inline: var(--cds2-spacing-md);
     gap: var(--cds2-spacing-md);
 
-    & .capra-TextInput-module-I5TDpa-input {
+    &:not(:has(.capra-TextInput-module-pTHfnG-leadingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    &:not(:has(.capra-TextInput-module-pTHfnG-trailingSlot)) .capra-TextInput-module-pTHfnG-input {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-input {
       height: calc(var(--cds2-dimension-component-md) - 2px);
       font: var(--cds2-typography-body-md-normal);
     }
+
+    & .capra-TextInput-module-pTHfnG-leadingSlot {
+      padding-inline-start: var(--cds2-spacing-md);
+    }
+
+    & .capra-TextInput-module-pTHfnG-trailingSlot {
+      padding-inline-end: var(--cds2-spacing-md);
+    }
   }
 
-  & .capra-TextInput-module-I5TDpa-leadingSlot, & .capra-TextInput-module-I5TDpa-trailingSlot {
+  & .capra-TextInput-module-pTHfnG-leadingSlot, & .capra-TextInput-module-pTHfnG-trailingSlot {
     align-items: center;
     gap: var(--cds2-spacing-xs);
     color: var(--cds2-color-foreground-subtle);
@@ -435,7 +465,7 @@
     display: inline-flex;
   }
 
-  & .capra-TextInput-module-I5TDpa-errorIndicator {
+  & .capra-TextInput-module-pTHfnG-errorIndicator {
     color: var(--cds2-color-foreground-danger-default);
     flex-shrink: 0;
     justify-content: center;
@@ -443,7 +473,7 @@
     display: inline-flex;
   }
 
-  & .capra-TextInput-module-I5TDpa-warningIndicator {
+  & .capra-TextInput-module-pTHfnG-warningIndicator {
     color: var(--cds2-color-foreground-warning-default);
     flex-shrink: 0;
     justify-content: center;
@@ -2232,15 +2262,15 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
     color: var(--cds2-color-foreground-warning-default);
   }
 }
-.capra-Modal-module-5vfSOW-overlay {
+.capra-Modal-module-j-u8iq-overlay {
   background-color: var(--cds2-color-background-scrim);
-  animation: capra-Modal-module-5vfSOW-overlayShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
-  z-index: 1000;
+  animation: capra-Modal-module-j-u8iq-overlayShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
+  z-index: 10000;
   position: fixed;
   inset: 0;
 }
 
-.capra-Modal-module-5vfSOW-surface {
+.capra-Modal-module-j-u8iq-surface {
   background-color: var(--cds2-color-background-panel-solid);
   border-radius: var(--cds2-radius-lg);
   border: var(--cds2-border-default);
@@ -2248,7 +2278,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   box-shadow: var(--cds2-shadow-high-down);
   max-width: 100%;
   max-height: min(80vh, 100vh - 48px);
-  animation: capra-Modal-module-5vfSOW-contentShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
+  animation: capra-Modal-module-j-u8iq-contentShow var(--cds2-motion-duration-medium-1) var(--cds2-motion-easing-standard);
   flex-direction: column;
   padding: 0;
   display: flex;
@@ -2271,7 +2301,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-.capra-Modal-module-5vfSOW-header {
+.capra-Modal-module-j-u8iq-header {
   padding: var(--cds2-spacing-md) var(--cds2-spacing-lg);
   border-bottom: var(--cds2-border-default);
   border-color: var(--cds2-color-border-neutral-subtle);
@@ -2282,21 +2312,21 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-headerLeading {
+.capra-Modal-module-j-u8iq-headerLeading {
   align-items: center;
   gap: var(--cds2-spacing-md);
   flex: 1;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-expandedTitleLayout {
+.capra-Modal-module-j-u8iq-expandedTitleLayout {
   align-items: center;
   gap: var(--cds2-spacing-md);
   flex-direction: row;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-content {
+.capra-Modal-module-j-u8iq-content {
   padding: var(--cds2-spacing-lg);
   flex-direction: column;
   flex: 1;
@@ -2304,14 +2334,14 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   overflow-y: auto;
 }
 
-.capra-Modal-module-5vfSOW-footer {
+.capra-Modal-module-j-u8iq-footer {
   padding: var(--cds2-spacing-md) var(--cds2-spacing-lg);
   border-top: var(--cds2-border-default);
   border-color: var(--cds2-color-border-neutral-subtle);
   background-color: var(--cds2-color-background-neutral-subtle);
 }
 
-.capra-Modal-module-5vfSOW-expandedFooterLayout {
+.capra-Modal-module-j-u8iq-expandedFooterLayout {
   justify-content: space-between;
   align-items: center;
   gap: var(--cds2-spacing-md);
@@ -2319,7 +2349,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-footerActions {
+.capra-Modal-module-j-u8iq-footerActions {
   justify-content: flex-end;
   align-items: center;
   gap: var(--cds2-spacing-md);
@@ -2328,20 +2358,20 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationSurface {
+.capra-Modal-module-j-u8iq-confirmationSurface {
   border-radius: var(--cds2-radius-md);
   width: min(400px, 100vw - 48px);
   box-shadow: var(--cds2-shadow-high-down);
   padding: var(--cds2-spacing-2xl) var(--cds2-spacing-2xl) var(--cds2-spacing-xl);
 }
 
-.capra-Modal-module-5vfSOW-confirmationLayout {
+.capra-Modal-module-j-u8iq-confirmationLayout {
   align-items: flex-start;
   gap: var(--cds2-spacing-lg);
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationIcon {
+.capra-Modal-module-j-u8iq-confirmationIcon {
   width: var(--cds2-dimension-component-sm);
   height: var(--cds2-dimension-component-sm);
   flex-shrink: 0;
@@ -2370,19 +2400,19 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-.capra-Modal-module-5vfSOW-confirmationBody {
+.capra-Modal-module-j-u8iq-confirmationBody {
   gap: var(--cds2-spacing-md);
   flex-direction: column;
   flex: 1;
   display: flex;
 }
 
-.capra-Modal-module-5vfSOW-confirmationMessage {
+.capra-Modal-module-j-u8iq-confirmationMessage {
   font: var(--cds2-typography-body-md-normal);
   margin: 0;
 }
 
-.capra-Modal-module-5vfSOW-confirmationActions {
+.capra-Modal-module-j-u8iq-confirmationActions {
   justify-content: flex-end;
   gap: var(--cds2-spacing-md);
   width: 100%;
@@ -2390,7 +2420,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   display: flex;
 }
 
-@keyframes capra-Modal-module-5vfSOW-overlayShow {
+@keyframes capra-Modal-module-j-u8iq-overlayShow {
   from {
     opacity: 0;
   }
@@ -2400,7 +2430,7 @@ input:disabled + .capra-Radio-module-ZI7rzq-inner:after {
   }
 }
 
-@keyframes capra-Modal-module-5vfSOW-contentShow {
+@keyframes capra-Modal-module-j-u8iq-contentShow {
   from {
     opacity: 0;
     transform: translate(-50%, -20px) scale(.96);

package/docs/conventions--docs.md

@@ -0,0 +1,186 @@
+# Conventions
+
+When building and consuming Capra components, we follow specific conventions to maintain a healthy codebase.
+
+### Semantic Properties
+
+Certain properties of Capra components have well-defined, consistent uses.
+
+| Prop         | Purpose                                                                                          | Possible Values                                                |
+| ------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `appearance` | Change the colors of a component using semantic intent, e.g. a danger `Button` when deleting     | `default`, `info`, `danger`, `warning`, `success`, `highlight` |
+| `color`      | Change the color of a component to a specific color, e.g. a teal `Ribbon`                        | Component-specific                                             |
+| `layout`     | Alter the component's layout, e.g. a horizontal input field with label                           | Component-specific                                             |
+| `size`       | Specify the size of the component                                                                | `xs`, `sm`, `md`, `lg`, `xl`                                   |
+| `variant`    | Specify a different visual treatment for the component, e.g. a dot `Badge` vs. a counter `Badge` | Component-specific                                             |
+
+For props where the possible values are pre-defined, a component may utilize the full set or a subset of the possible values.
+
+### Styling Overrides
+
+Capra components are built according to our design system specifications. They should rarely need to be styled differently than what is provided out-of-the-box. In the event custom styling is required, we provide a consistent escape hatch across all of our components for passing a CSS class name: `FORCE__className`.
+
+In your application, you can apply a style override like this:
+
+```tsx
+import { Text } from '@capra/core';
+import styles from './Component.modules.css';
+
+export function Component(props) {
+  return <Text FORCE__className={styles.text}>Hello world</Text>;
+}
+```
+
+Note that using this prop should be a rarity. Adding styles here is also somewhat brittle. While we do provide this escape hatch, we make no guarantees that the styles applied will apply correctly across version updates, e.g. a style override targeting a specific HTML structure within a Capra component breaks because the component was refactored to use a different HTML structure. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. Please use it responsibly.
+
+## Client-side Routing
+
+Capra components such as `Link` and `ButtonLink` render links that perform navigation when the user interacts with them. Each component that supports link behavior accepts an `href` prop, which is passed to the underlying `<a>` element.
+
+By default, links perform native browser navigation when they are interacted with. However, Capra supports overriding this behavior using a client-side router of your choice. Set this up once in the root of your app, and any Capra link component will automatically navigate using your router.
+
+Note that external links to different origins will not trigger client side routing, and will use native browser navigation. Additionally, if the link has a target other than `"_self"`, uses the `download` attribute, or the user presses modifier keys such as `Command` or `Alt` to change the default behavior, browser native navigation will occur instead of client side routing.
+
+### `RouterProvider`
+
+The `RouterProvider` component accepts two props: `navigate` and `useHref`. `navigate` should be set to a function received from your router for performing a client side navigation programmatically. `useHref` is an optional prop that converts a router-specific href to a native HTML href, e.g. prepending a base path. The following example shows the general pattern. Framework-specific examples are shown below.
+
+```tsx
+import {RouterProvider} from '@capra/core';
+import {useNavigate, useHref} from 'your-router';
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* ... */}
+    </RouterProvider>
+  );
+}
+```
+
+### Router Options
+
+All Capra link components accept a `routerOptions` prop, which is an object that is passed through to the client side router's `navigate` function as the second argument. This can be used to control any router-specific behaviors, such as scrolling, replacing instead of pushing to the history, etc.
+
+```tsx
+<Link href="/login" routerOptions={{replace: true}}>{/* ...*/}</Link>
+```
+
+When using TypeScript, you can configure the `RouterConfig` type globally so that all link components have auto complete and type safety using a type provided by your router.
+
+```tsx
+import type {RouterOptions} from 'your-router';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: RouterOptions
+  }
+}
+```
+
+### React Router
+
+The [useNavigate](https://reactrouter.com/en/main/hooks/use-navigate) hook from `react-router-dom` returns a `navigate` function you can pass to `RouterProvider`. The [useHref](https://reactrouter.com/en/main/hooks/use-href) hook can also be provided if you're using React Router's `basename` option. Ensure that the component that calls `useNavigate` and renders `RouterProvider` is inside the router component (e.g. `BrowserRouter`) so that it has access to React Router's internal context. The React Router `<Routes>` element should also be defined inside Capra's `<RouterProvider>` so that links inside the rendered routes have access to the router.
+
+```tsx
+import {BrowserRouter, useNavigate, useHref, type NavigateOptions} from 'react-router-dom';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NavigateOptions
+  }
+}
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <RouterProvider navigate={navigate} useHref={useHref}>
+      {/* Your app here... */}
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        {/* ... */}
+      </Routes>
+    </RouterProvider>
+  );
+}
+
+<BrowserRouter>
+  <App />
+</BrowserRouter>
+```
+
+### Next.js App Router
+
+The [useRouter](https://nextjs.org/docs/app/api-reference/functions/use-router) hook from `next/navigation` returns a router object that can be used to perform navigation. `RouterProvider` should be rendered from a client component at the root of each page or layout that includes Capra links. You can create a new client component for this, or combine it with other top-level providers as described in the [Next.js docs](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#using-context-providers).
+
+```tsx
+// app/provider.tsx
+"use client";
+
+import {useRouter} from 'next/navigation';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NonNullable<Parameters<ReturnType<typeof useRouter>['push']>[1]>
+  }
+}
+
+export function ClientProviders({children}) {
+  const router = useRouter();
+
+  return (
+    <RouterProvider navigate={router.push}>
+      {children}
+    </RouterProvider>
+  );
+}
+```
+
+Then, in your page or layout server component, wrap your app in the `ClientProviders` component that you defined.
+
+```tsx
+// app/layout.tsx
+import {ClientProviders} from './provider';
+
+export default function RootLayout({children}) {
+  return (
+    <html>
+      <body>
+        <ClientProviders>{children}</ClientProviders>
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js Pages Router
+
+The [useRouter](https://nextjs.org/docs/pages/api-reference/functions/use-router) hook from `next/router` returns a router object that can be used to perform navigation. `RouterProvider` should be rendered at the root of each page that includes Capra links, or in `pages/_app.tsx` to add it to all pages.
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import {useRouter, type NextRouter} from 'next/router';
+import {RouterProvider} from '@capra/core';
+
+declare module '@capra/core' {
+  interface RouterConfig {
+    routerOptions: NonNullable<Parameters<NextRouter['push']>[2]>
+  }
+}
+
+export default function MyApp({Component, pageProps}: AppProps) {
+  const router = useRouter();
+
+  return (
+    <RouterProvider navigate={(href, opts) => router.push(href, undefined, opts)}>
+      <Component {...pageProps} />
+    </RouterProvider>
+  );
+}
+```