Skip to content

Commit 2a6f3f9

Browse files
diogo-filipe-costadiogo-filipe-costa
committed
docs(storybook): refine link family stories
1 parent 6785a68 commit 2a6f3f9

File tree

3 files changed

+194
-13
lines changed

3 files changed

+194
-13
lines changed

‎packages/react-components/src/components/LinkAction/LinkAction.stories.tsx‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,44 @@
11
import type { Meta, StoryObj } from '@storybook/react-vite';
2+
import { ArgTypes, Description, Stories, Title } from '@storybook/addon-docs/blocks';
23
import { LinkAction, type LinkActionProps } from './LinkAction';
34

45
const meta: Meta<LinkActionProps> = {
56
title: 'Components/Link/Action',
67
component: LinkAction,
78
parameters: {
89
layout: 'padded',
10+
docsNamespaceArgKeys: ['href'],
911
docs: {
1012
description: {
1113
component:
1214
'LinkAction is the canonical React surface for the prominent Link / Action pattern. It keeps the toolkit structure, always renders the coloured circular arrow icon, and lets you customise the visible label, destination, and whether the link opens in a new tab. Standard anchor attributes still pass through when you need them.',
1315
},
16+
page: () => (
17+
<>
18+
<Title />
19+
<Description />
20+
21+
<h2>How to use LinkAction</h2>
22+
<p>
23+
Use <code>LinkAction</code> for the prominent action-style link that
24+
moves people forward in a journey. Pass the visible label with
25+
<code>children</code>, the destination with <code>href</code>, and
26+
set <code>openInNewWindow</code> when the destination should open in
27+
a new tab.
28+
</p>
29+
<p>
30+
<code>className</code> is for layout or integration hooks only.
31+
Anchor attributes such as <code>aria-*</code> still pass through
32+
when you need them.
33+
</p>
34+
35+
<h2>Props</h2>
36+
<ArgTypes of={LinkAction} exclude={['ref']} />
37+
38+
<h2>Examples</h2>
39+
<Stories title="Examples" />
40+
</>
41+
),
1442
},
1543
},
1644
tags: ['autodocs'],
@@ -21,11 +49,13 @@ const meta: Meta<LinkActionProps> = {
2149
argTypes: {
2250
children: {
2351
control: 'text',
24-
description: 'Visible link text. Keep it short and action-led.',
52+
description:
53+
'Visible link text. Keep it short, action-led, and clear about where the link goes.',
2554
},
2655
href: {
2756
control: 'text',
28-
description: 'Destination URL or fragment for the link action.',
57+
description:
58+
'Destination URL or fragment for the link action. This is the real link target, not just display text.',
2959
},
3060
openInNewWindow: {
3161
control: 'boolean',
@@ -35,14 +65,15 @@ const meta: Meta<LinkActionProps> = {
3565
className: {
3666
control: false,
3767
description:
38-
'Additional classes applied to the wrapper element. Use this for layout hooks only.',
68+
'Additional classes applied to the wrapper element. Use this for layout hooks or integration targets only.',
3969
table: {
4070
category: 'Advanced',
4171
},
4272
},
4373
ref: {
4474
control: false,
45-
description: 'React ref for the rendered anchor element.',
75+
description:
76+
'React ref for the rendered anchor element when you need direct DOM access.',
4677
table: {
4778
category: 'Advanced',
4879
},
@@ -54,11 +85,36 @@ export default meta;
5485
type Story = StoryObj<LinkActionProps>;
5586

5687
export const Default: Story = {
88+
args: {
89+
children: 'Find a minor injuries unit',
90+
href: 'https://www.nhs.uk/service-search/minor-injuries-unit/locationsearch/551',
91+
},
5792
parameters: {
93+
controls: {
94+
disable: true,
95+
},
5896
docs: {
5997
description: {
6098
story:
61-
'Interactive link action example. Use the controls to change the label, destination, and `openInNewWindow` behaviour.',
99+
'A realistic in-journey action link with the standard icon and label treatment.',
100+
},
101+
},
102+
},
103+
};
104+
105+
export const Builder: Story = {
106+
args: {
107+
children: 'Find a minor injuries unit',
108+
href: 'https://www.nhs.uk/service-search/minor-injuries-unit/locationsearch/551',
109+
},
110+
parameters: {
111+
controls: {
112+
include: ['children', 'href', 'openInNewWindow'],
113+
},
114+
docs: {
115+
description: {
116+
story:
117+
'Use the Builder controls to experiment with the label, destination, and `openInNewWindow` behaviour.',
62118
},
63119
},
64120
},
@@ -69,6 +125,9 @@ export const OpenInNewWindow: Story = {
69125
openInNewWindow: true,
70126
},
71127
parameters: {
128+
controls: {
129+
disable: true,
130+
},
72131
docs: {
73132
description: {
74133
story:

‎packages/react-components/src/components/LinkIcon/LinkIcon.stories.tsx‎

Lines changed: 71 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import type { Meta, StoryObj } from '@storybook/react-vite';
2+
import { ArgTypes, Description, Stories, Title } from '@storybook/addon-docs/blocks';
23
import iconManifest from '@ourfuturehealth/toolkit/assets/icons/manifest.json';
34
import { LinkIcon, type LinkIconProps } from './LinkIcon';
45

@@ -16,6 +17,32 @@ const meta: Meta<LinkIconProps> = {
1617
component:
1718
'LinkIcon is the canonical React surface for the Link / Icon pattern. Use `iconPosition` to switch between back-navigation and forward or external link patterns, choose any toolkit sprite icon with `iconName`, change the emphasis with `size`, and use `openInNewWindow` when the destination should open in a new tab. If you leave `iconName` unset, the component defaults to `ChevronLeft` on the left and `Launch` on the right.',
1819
},
20+
page: () => (
21+
<>
22+
<Title />
23+
<Description />
24+
25+
<h2>How to use LinkIcon</h2>
26+
<p>
27+
Use <code>LinkIcon</code> when the icon is part of the link
28+
pattern. Pass the visible label with <code>children</code>, the
29+
destination with <code>href</code>, and choose the icon side with
30+
<code>iconPosition</code>.
31+
</p>
32+
<p>
33+
Leave <code>iconName</code> unset to use the default icon for the
34+
chosen position. Set <code>openInNewWindow</code> when the link
35+
opens externally, and use <code>size</code> to choose compact or
36+
medium emphasis.
37+
</p>
38+
39+
<h2>Props</h2>
40+
<ArgTypes of={LinkIcon} exclude={['ref']} />
41+
42+
<h2>Examples</h2>
43+
<Stories title="Examples" />
44+
</>
45+
),
1946
},
2047
},
2148
tags: ['autodocs'],
@@ -28,7 +55,8 @@ const meta: Meta<LinkIconProps> = {
2855
argTypes: {
2956
children: {
3057
control: 'text',
31-
description: 'Visible link text. The icon should support the label, not replace it.',
58+
description:
59+
'Visible link text. The icon should support the label, not replace it.',
3260
},
3361
href: {
3462
control: 'text',
@@ -38,7 +66,7 @@ const meta: Meta<LinkIconProps> = {
3866
control: 'select',
3967
options: iconNameOptions,
4068
description:
41-
'Toolkit icon name from the generated sprite manifest. Defaults to `ChevronLeft` for left icons and `Launch` for right icons.',
69+
'Toolkit icon name from the generated sprite manifest. Leave it unset to use `ChevronLeft` for left icons and `Launch` for right icons.',
4270
},
4371
iconColor: {
4472
control: 'color',
@@ -65,14 +93,15 @@ const meta: Meta<LinkIconProps> = {
6593
className: {
6694
control: false,
6795
description:
68-
'Additional classes applied to the wrapper element. Use this for layout hooks only.',
96+
'Additional classes applied to the wrapper element. Use this for layout hooks or integration targets only.',
6997
table: {
7098
category: 'Advanced',
7199
},
72100
},
73101
ref: {
74102
control: false,
75-
description: 'React ref for the rendered anchor element.',
103+
description:
104+
'React ref for the rendered anchor element when you need direct DOM access.',
76105
table: {
77106
category: 'Advanced',
78107
},
@@ -84,11 +113,42 @@ export default meta;
84113
type Story = StoryObj<LinkIconProps>;
85114

86115
export const Default: Story = {
116+
args: {
117+
children: 'Go back',
118+
href: '#',
119+
iconPosition: 'left',
120+
size: 'small',
121+
},
87122
parameters: {
123+
controls: {
124+
disable: true,
125+
},
88126
docs: {
89127
description: {
90128
story:
91-
'Interactive back-navigation example. Use the controls to explore `iconPosition`, `iconName`, `size`, and `openInNewWindow`.',
129+
'A realistic back-navigation example using the default left icon and compact size.',
130+
},
131+
},
132+
},
133+
};
134+
135+
export const Builder: Story = {
136+
parameters: {
137+
controls: {
138+
include: [
139+
'children',
140+
'href',
141+
'iconName',
142+
'iconColor',
143+
'iconPosition',
144+
'openInNewWindow',
145+
'size',
146+
],
147+
},
148+
docs: {
149+
description: {
150+
story:
151+
'Use the Builder controls to explore the icon position, icon name, icon colour, size, and new-window behaviour.',
92152
},
93153
},
94154
},
@@ -104,6 +164,9 @@ export const RightIcon: Story = {
104164
openInNewWindow: true,
105165
},
106166
parameters: {
167+
controls: {
168+
disable: true,
169+
},
107170
docs: {
108171
description: {
109172
story:
@@ -124,6 +187,9 @@ export const CustomIconColour: Story = {
124187
openInNewWindow: true,
125188
},
126189
parameters: {
190+
controls: {
191+
disable: true,
192+
},
127193
docs: {
128194
description: {
129195
story:

‎packages/react-components/src/components/LinkSkip/LinkSkip.stories.tsx‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import type { Meta, StoryObj } from '@storybook/react-vite';
2+
import { ArgTypes, Description, Stories, Title } from '@storybook/addon-docs/blocks';
23
import { LinkSkip, type LinkSkipProps } from './LinkSkip';
34

45
const getSkipTargetId = (href?: string) =>
@@ -32,11 +33,36 @@ const meta: Meta<LinkSkipProps> = {
3233
component: LinkSkip,
3334
parameters: {
3435
layout: 'padded',
36+
docsNamespaceArgKeys: ['href'],
3537
docs: {
3638
description: {
3739
component:
3840
'LinkSkip is the canonical React surface for the Link / Skip pattern. It defaults to `#maincontent` and "Skip to main content", and you normally only change the label or target when users need to skip somewhere more specific. Standard anchor attributes still pass through when you need them.',
3941
},
42+
page: () => (
43+
<>
44+
<Title />
45+
<Description />
46+
47+
<h2>How to use LinkSkip</h2>
48+
<p>
49+
Use <code>LinkSkip</code> as the first focusable element on the
50+
page. Pass the visible label with <code>children</code> and the
51+
target with <code>href</code>.
52+
</p>
53+
<p>
54+
Most consumers only need the default <code>#maincontent</code>{' '}
55+
target. Change it only when the page needs to jump somewhere more
56+
specific, such as search results or a filtered section.
57+
</p>
58+
59+
<h2>Props</h2>
60+
<ArgTypes of={LinkSkip} exclude={['ref']} />
61+
62+
<h2>Examples</h2>
63+
<Stories title="Examples" />
64+
</>
65+
),
4066
},
4167
},
4268
tags: ['autodocs'],
@@ -58,14 +84,15 @@ const meta: Meta<LinkSkipProps> = {
5884
className: {
5985
control: false,
6086
description:
61-
'Additional classes applied to the anchor element. Use this only for layout hooks.',
87+
'Additional classes applied to the anchor element. Use this only for layout hooks or integration targets.',
6288
table: {
6389
category: 'Advanced',
6490
},
6591
},
6692
ref: {
6793
control: false,
68-
description: 'React ref for the rendered anchor element.',
94+
description:
95+
'React ref for the rendered anchor element when you need direct DOM access.',
6996
table: {
7097
category: 'Advanced',
7198
},
@@ -77,12 +104,38 @@ export default meta;
77104
type Story = StoryObj<LinkSkipProps>;
78105

79106
export const Default: Story = {
107+
args: {
108+
children: 'Skip to main content',
109+
href: '#maincontent',
110+
},
111+
render: renderLinkSkipStory,
112+
parameters: {
113+
controls: {
114+
disable: true,
115+
},
116+
docs: {
117+
description: {
118+
story:
119+
'The standard skip link that jumps straight to the main content region.',
120+
},
121+
},
122+
},
123+
};
124+
125+
export const Builder: Story = {
126+
args: {
127+
children: 'Skip to main content',
128+
href: '#maincontent',
129+
},
80130
render: renderLinkSkipStory,
81131
parameters: {
132+
controls: {
133+
include: ['children', 'href'],
134+
},
82135
docs: {
83136
description: {
84137
story:
85-
'Interactive default example. Use the controls to change the skip-link label and fragment target.',
138+
'Use the Builder controls to change the skip-link label and fragment target.',
86139
},
87140
},
88141
},
@@ -95,6 +148,9 @@ export const CustomTargetAndLabel: Story = {
95148
},
96149
render: renderLinkSkipStory,
97150
parameters: {
151+
controls: {
152+
disable: true,
153+
},
98154
docs: {
99155
description: {
100156
story:

0 commit comments

Comments
 (0)