@react-foundry/anchor 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (C) 2019-2025 Crown Copyright
+Copyright (C) 2019-2026 Daniel A.C. Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+React Foundry - Anchor
+======================
+
+A drop in replacement for the HTML `<a>` tag that works with [React Router].
+
+
+Preview
+-------
+
+![Preview][Preview]
+
+
+Using this package
+------------------
+
+First install the package into your project:
+
+```shell
+npm install -S @react-foundry/anchor
+```
+
+Then use it in your code as follows:
+
+```js
+import React, { createElement as h } from 'react';
+import { A } from '@react-foundry/anchor';
+
+export const MyComponent = props => (
+  <A href="#">My link</A>
+);
+
+export default MyComponent;
+```
+
+
+Working on this package
+-----------------------
+
+Before working on this package you must install its dependencies using
+the following command:
+
+```shell
+pnpm install
+```
+
+
+### Testing
+
+```shell
+npm test
+```
+
+
+### Building
+
+```shell
+npm run build
+```
+
+
+### Clean-up
+
+```shell
+npm run clean
+```
+
+
+[React Router]: https://reacttraining.com/react-router/
+[Preview]: ../../__image_snapshots__/storyshots-itest-ts-image-storyshots-components-anchor-standard-1-snap.png

package/dist/Anchor.d.ts

@@ -0,0 +1,11 @@
+import { AnchorHTMLAttributes, FC, ReactNode } from 'react';
+import { StandardProps } from '@react-foundry/component-helpers';
+import '../assets/Anchor.scss';
+export type AnchorProps = StandardProps & AnchorHTMLAttributes<HTMLAnchorElement> & {
+    children?: ReactNode;
+    /** Whether to force the link to be treated as external (useful for internal links that are NOT handled by the application) */
+    forceExternal?: boolean;
+};
+export declare const Anchor: FC<AnchorProps>;
+export default Anchor;
+export declare const A: FC<AnchorProps>;

package/dist/Anchor.js

@@ -0,0 +1,67 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A = exports.Anchor = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const client_component_helpers_1 = require("@react-foundry/client-component-helpers");
+const component_helpers_1 = require("@react-foundry/component-helpers");
+const router_1 = require("@react-foundry/router");
+const uri_1 = require("@react-foundry/uri");
+require("../assets/Anchor.scss");
+const supportedProtocols = [
+    'http:',
+    'https:'
+];
+const AnchorInner = ({ children, classBlock, classModifiers: _classModifiers = [], className, forceExternal = false, href, ...attrs }) => {
+    const isMounted = (0, client_component_helpers_1.useIsMounted)();
+    const active = (0, router_1.useIsActive)()(href || '');
+    const current = (0, router_1.useLocation)();
+    const classModifiers = [
+        active ? 'active' : '',
+        ...(Array.isArray(_classModifiers) ? _classModifiers : [_classModifiers])
+    ];
+    const classes = (0, component_helpers_1.classBuilder)('penultimate-anchor', classBlock, classModifiers, className);
+    const url = uri_1.URI.parse(href || '');
+    const unsupported = url.protocol !== '' && !supportedProtocols.includes(url.protocol || '');
+    const noPath = url.pathname === '';
+    const noSearch = url.search === '';
+    const noHash = url.hash === '';
+    const hashLink = noPath && noSearch;
+    const location = {
+        pathname: (noPath
+            ? current.pathname
+            : url?.pathname),
+        search: (hashLink
+            ? current.search
+            : url?.search),
+        hash: (noHash
+            ? '#'
+            : url?.hash)
+    };
+    const basicAnchor = (forceExternal ||
+        unsupported ||
+        url.hostname ||
+        !isMounted && hashLink ||
+        hashLink && noHash);
+    return (basicAnchor
+        ? ((0, jsx_runtime_1.jsx)("a", { ...attrs, className: classes(), href: href, children: children }))
+        : ((0, jsx_runtime_1.jsx)(router_1.Link, { ...attrs, "aria-current": active ? 'page' : undefined, className: classes(), to: location, children: children })));
+};
+const Anchor = ({ children, classBlock, classModifiers, className, forceExternal, href, ...attrs }) => {
+    const classes = (0, component_helpers_1.classBuilder)('penultimate-anchor', classBlock, classModifiers, className);
+    const props = {
+        ...attrs,
+        classBlock,
+        classModifiers,
+        className,
+        forceExternal,
+        href
+    };
+    const content = ((0, jsx_runtime_1.jsx)(AnchorInner, { ...props, children: children }));
+    return (!router_1.needSuspense ? content : ((0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: (0, jsx_runtime_1.jsx)("a", { ...attrs, className: classes(), href: href, children: children }), children: content })));
+};
+exports.Anchor = Anchor;
+exports.Anchor.displayName = 'A';
+exports.default = exports.Anchor;
+exports.A = exports.Anchor;

package/dist/Anchor.mjs

@@ -0,0 +1,63 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from 'react';
+import { useIsMounted } from '@react-foundry/client-component-helpers';
+import { classBuilder } from '@react-foundry/component-helpers';
+import { Link, needSuspense, useLocation, useIsActive } from '@react-foundry/router';
+import { URI } from '@react-foundry/uri';
+import '../assets/Anchor.scss';
+const supportedProtocols = [
+    'http:',
+    'https:'
+];
+const AnchorInner = ({ children, classBlock, classModifiers: _classModifiers = [], className, forceExternal = false, href, ...attrs }) => {
+    const isMounted = useIsMounted();
+    const active = useIsActive()(href || '');
+    const current = useLocation();
+    const classModifiers = [
+        active ? 'active' : '',
+        ...(Array.isArray(_classModifiers) ? _classModifiers : [_classModifiers])
+    ];
+    const classes = classBuilder('penultimate-anchor', classBlock, classModifiers, className);
+    const url = URI.parse(href || '');
+    const unsupported = url.protocol !== '' && !supportedProtocols.includes(url.protocol || '');
+    const noPath = url.pathname === '';
+    const noSearch = url.search === '';
+    const noHash = url.hash === '';
+    const hashLink = noPath && noSearch;
+    const location = {
+        pathname: (noPath
+            ? current.pathname
+            : url?.pathname),
+        search: (hashLink
+            ? current.search
+            : url?.search),
+        hash: (noHash
+            ? '#'
+            : url?.hash)
+    };
+    const basicAnchor = (forceExternal ||
+        unsupported ||
+        url.hostname ||
+        !isMounted && hashLink ||
+        hashLink && noHash);
+    return (basicAnchor
+        ? (_jsx("a", { ...attrs, className: classes(), href: href, children: children }))
+        : (_jsx(Link, { ...attrs, "aria-current": active ? 'page' : undefined, className: classes(), to: location, children: children })));
+};
+export const Anchor = ({ children, classBlock, classModifiers, className, forceExternal, href, ...attrs }) => {
+    const classes = classBuilder('penultimate-anchor', classBlock, classModifiers, className);
+    const props = {
+        ...attrs,
+        classBlock,
+        classModifiers,
+        className,
+        forceExternal,
+        href
+    };
+    const content = (_jsx(AnchorInner, { ...props, children: children }));
+    return (!needSuspense ? content : (_jsx(Suspense, { fallback: _jsx("a", { ...attrs, className: classes(), href: href, children: children }), children: content })));
+};
+Anchor.displayName = 'A';
+export default Anchor;
+export const A = Anchor;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@react-foundry/anchor",
+  "version": "0.1.0",
+  "description": "A drop-in replacement for the 'a' element.",
+  "main": "dist/Anchor.js",
+  "sass": "assets/Anchor.scss",
+  "exports": {
+    ".": {
+      "sass": "./assets/Anchor.scss",
+      "types": "./dist/Anchor.d.ts",
+      "import": "./dist/Anchor.mjs",
+      "require": "./dist/Anchor.js",
+      "default": "./dist/Anchor.mjs"
+    }
+  },
+  "files": [
+    "/assets",
+    "/dist"
+  ],
+  "author": "Daniel A.C. Martin <npm@daniel-martin.co.uk> (http://daniel-martin.co.uk/)",
+  "license": "MIT",
+  "keywords": [
+    "react-components"
+  ],
+  "dependencies": {
+    "@react-foundry/client-component-helpers": "^0.1.0",
+    "@react-foundry/component-helpers": "^0.1.0",
+    "@react-foundry/router": "^0.1.0",
+    "@react-foundry/uri": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@react-foundry/docs-components": "^0.1.0",
+    "@storybook/addon-docs": "^9.1.17",
+    "react": "^19.2.3"
+  },
+  "peerDependenciesMeta": {
+    "@react-foundry/docs-components": {
+      "optional": true
+    },
+    "@storybook/addon-docs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.2.9",
+    "jest": "30.2.0",
+    "jest-environment-jsdom": "30.2.0",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3",
+    "@react-foundry/component-test-helpers": "0.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -m es2022 && find dist -name '*.js' -exec sh -c 'mv \"$0\" \"${0%.js}.mjs\"' {} \\;",
+    "build:cjs": "tsc",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "module": "dist/Anchor.mjs",
+  "typings": "dist/Anchor.d.ts"
+}