website: Update Anchor documentation

apps/website/src/examples/Anchor.asbutton.tsx

@@ -0,0 +1,14 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Anchor } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Anchor as='button' onClick={console.log('Button clicked!')}>
+      Anchor as a button
+    </Anchor>
+  );
+};

apps/website/src/examples/Anchor.main.tsx

@@ -6,5 +6,5 @@ import * as React from 'react';
 import { Anchor } from '@itwin/itwinui-react';
 
 export default () => {
-  return <Anchor>This is an anchor.</Anchor>;
+  return <Anchor href='https://www.example.com/'>Example Site</Anchor>;
 };

apps/website/src/examples/index.tsx

@@ -23,6 +23,7 @@ export { default as AvatarSizesExample } from './Avatar.sizes';
 export { default as AvatarStatusesExample } from './Avatar.statuses';
 
 export { default as AnchorMainExample } from './Anchor.main';
+export { default as AnchorAsButtonExample } from './Anchor.asbutton';
 
 export { default as BadgeMainExample } from './Badge.main';
 export { default as BadgeSoftExample } from './Badge.soft';

apps/website/src/pages/docs/anchor.mdx

@@ -9,19 +9,37 @@ thumbnail: Anchor
 
 import PropsTable from '~/components/PropsTable.astro';
 import LiveExample from '~/components/LiveExample.astro';
-import Placeholder from '~/components/Placeholder.astro';
+import RelatedComponents from '~/components/RelatedComponents.astro';
 import * as AllExamples from '~/examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='typography-anchor' />
-
 <LiveExample src='Anchor.main.tsx' truncate={false}>
   <AllExamples.AnchorMainExample client:load />
 </LiveExample>
 
+The anchor's `href` attribute is the destination URL while the text within the anchor element should describe the link's name.
+
+## Usage
+
 Consider using a named anchor when you want the user to land not only on a specific page, but also to arrive at a content area that may be below the fold so the user does not have to scroll to discover it.
 
+A common question is whether to use an anchor or a [button](button). The basic rule of thumb is an anchor takes you to another page, whereas a button performs an action. For more details, read [this article on buttons vs links](https://yatil.net/blog/buttons-vs-links).
+
+### `as` prop
+
+The anchor component supports the polymorphic `as` prop to render the anchor as a button. This can be useful when the design requires a control which visually looks like an anchor but acts like a button, i.e. it performs an action within the same page, rather than navigating to a destination URL.
+
+<LiveExample src='Anchor.asbutton.tsx' truncate={false}>
+  <AllExamples.AnchorAsButtonExample client:load />
+</LiveExample>
+
+The `as` prop can also be used with `Link` components from different routers such as [Next.js](https://nextjs.org/docs/api-reference/next/link) and [React Router](https://reactrouter.com/en/main/components/link)
+
 ## Props
 
 <PropsTable path={frontmatter.propsPath} />
+
+## Related components
+
+<RelatedComponents components={[{ title: 'Button', url: 'button' }]} />