@codecademy/styleguide 78.5.6-alpha.ea1cbb.0 → 78.5.6-alpha.eca584.0

package/src/lib/Molecules/Tips/InfoTip/InfoTip.stories.tsx

@@ -4,17 +4,20 @@ import {
   FillButton,
   FlexBox,
   GridBox,
+  IconButton,
   InfoTip,
   Modal,
   Text,
 } from '@codecademy/gamut';
+import { SparkleIcon } from '@codecademy/gamut-icons';
 import type { Meta, StoryObj } from '@storybook/react';
-import { useRef, useState } from 'react';
+import { useState } from 'react';
 
 const meta: Meta<typeof InfoTip> = {
   component: InfoTip,
   args: {
     alignment: 'top-left',
+    ariaLabel: 'More information',
     info: `I am additional information about a nearby element or content.`,
   },
 };
@@ -28,7 +31,10 @@ export const Emphasis: Story = {
   },
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
+      <Text id="emphasis-text" mr={4}>
+        Some text that needs info
+      </Text>
+      <InfoTip {...args} ariaLabelledby="emphasis-text" />
     </FlexBox>
   ),
 };
@@ -38,10 +44,15 @@ export const Alignments: Story = {
     <GridBox gap={24} gridTemplateColumns="1fr 1fr" ml={8} py={64}>
       {(['top-right', 'top-left', 'bottom-right', 'bottom-left'] as const).map(
         (alignment) => {
+          const labelId = `alignment-${alignment}`;
           return (
             <Box key={alignment}>
-              <Text>{alignment}</Text>
-              <InfoTip {...args} alignment={alignment} />
+              <Text id={labelId}>{alignment}</Text>
+              <InfoTip
+                {...args}
+                alignment={alignment}
+                ariaLabelledby={labelId}
+              />
             </Box>
           );
         }
@@ -56,10 +67,51 @@ export const Placement: Story = {
   },
   render: (args) => (
     <FlexBox center>
-      <Text mr={4}>
+      <Text id="placement-text" mr={4}>
         This text is in a small space and needs floating placement
       </Text>{' '}
-      <InfoTip {...args} />
+      <InfoTip {...args} ariaLabelledby="placement-text" />
+    </FlexBox>
+  ),
+};
+
+export const AriaLabel: Story = {
+  render: (args) => (
+    <FlexBox center column gap={24} my={48} width={1}>
+      <FlexBox alignItems="center" gap={8}>
+        <Text fontSize={16} fontWeight="bold">
+          Using ariaLabel (no visible label text):
+        </Text>
+      </FlexBox>
+      <FlexBox alignItems="center" gap={8}>
+        <IconButton
+          icon={SparkleIcon}
+          tip="This tool needs to be explained in the InfoTip"
+          tipProps={{ placement: 'floating' }}
+          onClick={() => null}
+        />
+        <InfoTip
+          {...args}
+          ariaLabel="Learn more about this tool"
+          info="This is some helpful info about the tool represented by the IconButton"
+        />
+      </FlexBox>
+
+      <FlexBox alignItems="center" gap={8}>
+        <Text fontSize={16} fontWeight="bold">
+          Using ariaLabelledby (references visible text):
+        </Text>
+      </FlexBox>
+      <FlexBox alignItems="center" gap={8}>
+        <Text id="custom-info-id">
+          I am some helpful yet concise text that needs more explanation
+        </Text>
+        <InfoTip
+          alignment="bottom-left"
+          ariaLabelledby="custom-info-id"
+          info="I am clarifying information related to the concise text."
+        />
+      </FlexBox>
     </FlexBox>
   ),
 };
@@ -69,19 +121,16 @@ export const WithLinksOrButtons: Story = {
     placement: 'floating',
   },
   render: function WithLinksOrButtons(args) {
-    const ref = useRef<HTMLDivElement>(null);
-
-    const onClick = ({ isTipHidden }: { isTipHidden: boolean }) => {
-      if (!isTipHidden) ref.current?.focus();
-    };
-
     return (
       <FlexBox center py={64}>
-        <Text mr={4}>This text is in a small space and needs info </Text>{' '}
+        <Text id="links-text" mr={4}>
+          This text is in a small space and needs info
+        </Text>{' '}
         <InfoTip
           {...args}
+          ariaLabelledby="links-text"
           info={
-            <Text ref={ref} tabIndex={-1}>
+            <Text tabIndex={-1}>
               Hey! Here is a{' '}
               <Anchor href="https://giphy.com/search/nichijou">
                 cool link
@@ -93,7 +142,6 @@ export const WithLinksOrButtons: Story = {
               that is also super important.
             </Text>
           }
-          onClick={onClick}
         />
       </FlexBox>
     );
@@ -102,42 +150,35 @@ export const WithLinksOrButtons: Story = {
 
 export const KeyboardNavigation: Story = {
   render: function KeyboardNavigation() {
-    const floatingRef = useRef<HTMLDivElement>(null);
-    const inlineRef = useRef<HTMLDivElement>(null);
-
     const examples = [
       {
         title: 'Floating Placement',
         placement: 'floating' as const,
-        ref: floatingRef,
         links: ['Link 1', 'Link 2', 'Link 3'],
       },
       {
         title: 'Inline Placement',
         placement: 'inline' as const,
         alignment: 'bottom-right' as const,
-        ref: inlineRef,
         links: ['Link A', 'Link B'],
       },
     ];
 
     return (
-      <FlexBox center column gap={24} py={64}>
+      <FlexBox center flexDirection="column" gap={24} py={64}>
         <GridBox gap={16} gridTemplateColumns="1fr 1fr">
-          {examples.map(({ title, placement, alignment, ref, links }) => {
-            const onClick = ({ isTipHidden }: { isTipHidden: boolean }) => {
-              if (!isTipHidden) ref.current?.focus();
-            };
-
+          {examples.map(({ title, placement, alignment, links }) => {
+            const labelId = `keyboard-nav-${placement}`;
             return (
               <FlexBox gap={8} key={placement}>
-                <Text fontSize={16} fontWeight="bold">
+                <Text fontSize={16} fontWeight="bold" id={labelId}>
                   {title}
                 </Text>
                 <InfoTip
                   alignment={alignment}
+                  ariaLabelledby={labelId}
                   info={
-                    <Text ref={ref} tabIndex={-1}>
+                    <Text>
                       {links.map((label, idx) => (
                         <>
                           {idx > 0 && ', '}
@@ -150,7 +191,6 @@ export const KeyboardNavigation: Story = {
                     </Text>
                   }
                   placement={placement}
-                  onClick={onClick}
                 />
               </FlexBox>
             );
@@ -162,6 +202,10 @@ export const KeyboardNavigation: Story = {
             Keyboard Navigation:
           </Text>
           <Box as="ul" fontSize={14} pl={16}>
+            <li>
+              <strong>Opening:</strong> Focus automatically moves to the tip
+              content when opened
+            </li>
             <li>
               <strong>Floating - Tab:</strong> Navigates forward through links,
               then wraps to button (contained)
@@ -224,8 +268,10 @@ export const InfoTipInsideModal: Story = {
             <Text>This modal contains an InfoTip below:</Text>
 
             <FlexBox alignItems="center" gap={8}>
-              <Text>Some text that needs explanation</Text>
-              <InfoTip {...args} />
+              <Text id="modal-infotip-text">
+                Some text that needs explanation
+              </Text>
+              <InfoTip {...args} ariaLabelledby="modal-infotip-text" />
             </FlexBox>
 
             <Text color="text-disabled" fontSize={14}>
@@ -253,11 +299,14 @@ export const ZIndex: Story = {
       <Box bg="paleBlue" zIndex={3}>
         I will not be behind the infotip, sad + unreadable
       </Box>
-      <InfoTip info="I am inline, cool" />
+      <InfoTip
+        ariaLabel="z-index example without override"
+        info="I am inline, cool"
+      />
       <Box bg="paleBlue" zIndex={3}>
         I will be behind the infotip, nice + great
       </Box>
-      <InfoTip {...args} />
+      <InfoTip {...args} ariaLabel="z-index example with override" />
     </FlexBox>
   ),
 };
@@ -265,7 +314,10 @@ export const ZIndex: Story = {
 export const Default: Story = {
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
+      <Text id="default-text" mr={4}>
+        Some text that needs info
+      </Text>
+      <InfoTip {...args} ariaLabelledby="default-text" />
     </FlexBox>
   ),
 };

package/src/lib/Organisms/ConnectedForm/ConnectedFormGroup/ConnectedFormGroup.mdx

@@ -61,6 +61,25 @@ A `ConnectedFormGroup` can be in one of three states: `default`, `error`, or `di
 
 <Canvas of={ConnectedFormGroupStories.States} />
 
+## InfoTip
+
+A `ConnectedFormGroup` can include an `infotip` prop to provide additional context.
+
+### Automatic labelling
+
+InfoTip buttons are automatically labelled by string field labels for accessibility.
+
+<Canvas of={ConnectedFormGroupStories.InfoTipAutoLabelling} />
+
+### ReactNode labels
+
+For ReactNode labels (e.g., styled text or icons), the InfoTip is automatically labelled by the field label. You can override this behavior by providing:
+
+- `ariaLabel` - provide a custom accessible name
+- `ariaLabelledby` - reference another element on the page, such as a section heading
+
+<Canvas of={ConnectedFormGroupStories.InfoTipWithReactNodeLabel} />
+
 ## Playground
 
 To see how a `ConnectedFormGroup` can be used in a `ConnectedForm`, check out the <LinkTo id="Organisms/ConnectedForm/ConnectedForm">ConnectedForm</LinkTo> page.

package/src/lib/Organisms/ConnectedForm/ConnectedFormGroup/ConnectedFormGroup.stories.tsx

@@ -2,7 +2,9 @@ import {
   ConnectedForm,
   ConnectedFormGroup,
   ConnectedFormGroupProps,
+  ConnectedInput,
   ConnectedRadioGroupInput,
+  Text,
   useConnectedForm,
 } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
@@ -119,3 +121,74 @@ export const States = () => {
     </ConnectedForm>
   );
 };
+
+export const InfoTipAutoLabelling: Story = {
+  render: () => (
+    <ConnectedForm
+      defaultValues={{ email: '' }}
+      onSubmit={(values) => action('Form Submitted')(values)}
+    >
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput, type: 'email' }}
+        infotip={{
+          info: 'We will never share your email with third parties.',
+          placement: 'floating',
+        }}
+        label="Email address"
+        name="email"
+      />
+    </ConnectedForm>
+  ),
+};
+
+export const InfoTipWithReactNodeLabel: Story = {
+  render: () => (
+    <ConnectedForm
+      defaultValues={{ username: '', password: '', apiKey: '' }}
+      onSubmit={(values) => action('Form Submitted')(values)}
+    >
+      <Text as="h3" id="api-section-heading" mb={8}>
+        API Configuration
+      </Text>
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput }}
+        infotip={{
+          alignment: 'bottom-left',
+          info: 'Choose a unique username between 3-20 characters.',
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            Username (automatic label)
+          </Text>
+        }
+        name="username"
+      />
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput, type: 'password' }}
+        infotip={{
+          info: 'Password must be at least 8 characters with one uppercase letter and one number.',
+          ariaLabel: 'Password requirements',
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            Password (ariaLabel)
+          </Text>
+        }
+        name="password"
+      />
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput }}
+        infotip={{
+          info: 'You can find your API key in the developer settings dashboard.',
+          ariaLabelledby: 'api-section-heading',
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            API Key (ariaLabelledby)
+          </Text>
+        }
+        name="apiKey"
+      />
+    </ConnectedForm>
+  ),
+};

package/src/lib/Organisms/GridForm/Fields.mdx

@@ -95,3 +95,22 @@ Hidden inputs can be used to include data that users can't see or modify with th
 We call it a "sweet container" so that bots do not immediately detect it as a honeypot input.
 
 <Canvas of={FieldsStories.SweetContainer} />
+
+## InfoTip
+
+Any field can include an `infotip` prop to provide additional context to users.
+
+### Automatic labelling
+
+InfoTip buttons are automatically labelled by string field labels for accessibility.
+
+<Canvas of={FieldsStories.InfoTipAutoLabelling} />
+
+### ReactNode labels
+
+For ReactNode labels, the InfoTip is automatically labelled by the field label. You can override this behavior by providing:
+
+- `ariaLabel` - provide a custom accessible name
+- `ariaLabelledby` - reference another element on the page, such as a section heading
+
+<Canvas of={FieldsStories.InfoTipWithReactNodeLabel} />

package/src/lib/Organisms/GridForm/Fields.stories.tsx

@@ -1,4 +1,4 @@
-import { FormGroup, GridForm, Input } from '@codecademy/gamut';
+import { FormGroup, GridForm, Input, Text } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
 import type { Meta, StoryObj } from '@storybook/react';
 
@@ -328,3 +328,64 @@ export const SweetContainer: Story = {
     ],
   },
 };
+
+export const InfoTipAutoLabelling: Story = {
+  args: {
+    fields: [
+      {
+        label: 'Email address',
+        name: 'email',
+        size: 9,
+        type: 'email',
+        infotip: {
+          info: 'We will never share your email with third parties.',
+          placement: 'floating',
+        },
+      },
+    ],
+  },
+};
+
+export const InfoTipWithReactNodeLabel: Story = {
+  render: (args) => (
+    <>
+      <Text as="h3" id="api-section-heading" mb={8}>
+        API Configuration
+      </Text>
+      <GridForm {...args} />
+    </>
+  ),
+  args: {
+    fields: [
+      {
+        label: <strong>Username (automatic label)</strong>,
+        name: 'username',
+        size: 9,
+        type: 'text',
+        infotip: {
+          info: 'Choose a unique username between 3-20 characters.',
+        },
+      },
+      {
+        label: <strong>Password (ariaLabel)</strong>,
+        name: 'password',
+        size: 9,
+        type: 'password',
+        infotip: {
+          info: 'Password must be at least 8 characters with one uppercase letter and one number.',
+          ariaLabel: 'Password requirements',
+        },
+      },
+      {
+        label: <strong>API Key (ariaLabelledby)</strong>,
+        name: 'apiKey',
+        size: 9,
+        type: 'text',
+        infotip: {
+          info: 'You can find your API key in the developer settings dashboard.',
+          ariaLabelledby: 'api-section-heading',
+        },
+      },
+    ],
+  },
+};

package/src/lib/Organisms/GridForm/Layout.mdx

@@ -34,7 +34,7 @@ Solo field form should always have their solo input be required. They should aut
 
 ## InfoTips
 
-A field can include our existing `InfoTip`. See the <LinkTo id="Molecules/Tips/InfoTip">InfoTip</LinkTo> story for more information on what props are available.
+A field can include our existing `InfoTip`. See the <LinkTo id="Molecules/Tips/InfoTip">Fields</LinkTo> story for specific accessibility tooling and <LinkTo id="Molecules/Tips/InfoTip">InfoTip</LinkTo> story for more information on what props are available.
 
 See the <LinkTo id="Atoms/FormInputs/Radio">Radio</LinkTo> story for an example of how to add a infotip to a radio option.
 

package/src/lib/Foundations/System/Props/About.mdx

@@ -1,81 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import {
-  AboutHeader,
-  addParentPath,
-  TableOfContents,
-} from '~styleguide/blocks';
-
-import { parameters as backgroundParameters } from './Background.mdx';
-import { parameters as borderParameters } from './Border.mdx';
-import { parameters as colorParameters } from './Color.mdx';
-import { parameters as flexParameters } from './Flex.mdx';
-import { parameters as gridParameters } from './Grid.mdx';
-import { parameters as layoutParameters } from './Layout.mdx';
-import { parameters as listParameters } from './List.mdx';
-import { parameters as positioningParameters } from './Positioning.mdx';
-import { parameters as shadowParameters } from './Shadow.mdx';
-import { parameters as spaceParameters } from './Space.mdx';
-import { parameters as typographyParameters } from './Typography.mdx';
-
-export const parameters = {
-  id: 'Foundations/System/Props',
-  title: 'Props',
-  subtitle:
-    'Reusable CSS-in-JS props with predictable behaviors and a consistent API for responsive CSS.',
-  status: 'current',
-  source: {
-    repo: 'gamut-styles',
-    githubLink:
-      'https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts',
-  },
-};
-
-<Meta title="Foundations/System/Props/About" />
-
-<AboutHeader {...parameters} />
-
-We provide a set of out of style functions out of the box through `@codecademy/gamut-styles` that are standardized throughout all of our components. These props are strongly typed and can be included as necessary on any styled component.
-
-System props have a few facets that are important to note:
-
-- They can some times represent multiple properties.
-- They may be restricted to specific token scales but will always have access to global css values like `initial` and `none`.
-- They may have a function that transforms the given value into a standardized value (e.g. `width={.5}` => `width: 50%`)
-
-We've grouped these into a few main groups that affect simliar behaviors: `layout`, `space`, `color`, `border`, `background`, `typography`, `positioning`, `grid`, `flex`, `shadow`.
-
-You may import these groups directly from `gamut-styles`.
-
-```tsx
-import { variance } from '@codecademy/variance';
-import { system } from '@codecademy/gamut-styles';
-
-const ExampleContainer = styled.div(
-  variance.compose(system.layout, system.positioning)
-);
-
-<ExampleContainer position="absolute" width="50px" height="50px" />;
-```
-
-Each system prop has 3 important features:
-
-- `properties`: Any number of CSS Properties this prop is responsible for.
-- `scale`: A set of values that determines valid inputs for each prop based on the selected theme and that theme's typing (e.g. if the `lxStudio` theme is being used, a scale of `colors` will restrict to the `lxStudio` theme's colors). These are generally aliases for more verbose or opaque CSS properties allowing you to specify a human readable name in your props. If a prop doesn't have a scale that means it accepts all valid `CSSType` values as props, however if it does have a scale it will only accept global values and keys of the provided scale.
-- `transform`: A function that changes the prop / scale value prior to adding it to the stylehseet. This allows us to add / change units for properties like `width` and `height`. Or ensure extra defaults or fallbacks are added dynamically.
-
-<TableOfContents
-  links={addParentPath(parameters.id, [
-    layoutParameters,
-    spaceParameters,
-    typographyParameters,
-    colorParameters,
-    borderParameters,
-    flexParameters,
-    gridParameters,
-    backgroundParameters,
-    positioningParameters,
-    shadowParameters,
-    listParameters,
-  ])}
-/>

package/src/lib/Foundations/System/Props/Background.mdx

@@ -1,30 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../../shared/elements';
-
-export const parameters = {
-  title: 'Background',
-  subtitle:
-    'Props for background manipulation (sizing / repitition / images), for background color see `colors`.',
-  status: 'current',
-};
-
-<Meta title="Foundations/System/Props/Background" />
-
-<AboutHeader {...parameters} />
-
-Background props control how background images and patterns are displayed on elements. These properties give you control over image sizing, positioning, and repetition behavior. For solid background colors, use the color props which connect to the theme's color palette.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-import myBg from './myBg.png';
-
-const BackgroundExample = styled.div(system.background);
-
-<BackgroundExample background={`url(${myBg}`} backgroundSize="cover" />;
-```
-
-<TokenTable rows={getPropRows('background')} columns={defaultColumns} />

package/src/lib/Foundations/System/Props/Border.mdx

@@ -1,33 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../../shared/elements';
-
-export const parameters = {
-  title: 'Border',
-  subtitle: 'Border styles',
-  status: 'updating',
-};
-
-<Meta title="Foundations/System/Props/Border" />
-
-<AboutHeader {...parameters} />
-
-Border props enable you to add and style borders on any side of an element. These properties support directional borders (top, right, bottom, left) as well as convenient shorthands for horizontal and vertical borders. Border radius values connect to the theme's `borderRadii` scale for consistent corner rounding.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const BorderExample = styled.div(system.border);
-
-<BorderExample
-  border={1}
-  borderLeft="none"
-  borderRightStyle="dotted"
-  borderRadius="md"
-/>;
-```
-
-<TokenTable rows={getPropRows('border')} columns={defaultColumns} />

package/src/lib/Foundations/System/Props/Color.mdx

@@ -1,28 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../../shared/elements';
-
-export const parameters = {
-  title: 'Color',
-  subtitle: 'Specific color properties',
-  status: 'current',
-};
-
-<Meta title="Foundations/System/Props/Color" />
-
-<AboutHeader {...parameters} />
-
-Color props control the foreground, background, and border colors of elements. All color values are restricted to your theme's color palette, ensuring consistent color usage throughout your application. The `bg` shorthand provides a convenient way to set background colors quickly.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const ColorExample = styled.div(system.color);
-
-<ColorExample bg="navy" textColor="gray-100" borderColor="blue" />;
-```
-
-<TokenTable rows={getPropRows('color')} columns={defaultColumns} />

package/src/lib/Foundations/System/Props/Flex.mdx

@@ -1,28 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../../shared/elements';
-
-export const parameters = {
-  title: 'Flex',
-  subtitle: 'Flex specific properties',
-  status: 'current',
-};
-
-<Meta title="Foundations/System/Props/Flex" />
-
-<AboutHeader {...parameters} />
-
-Flex props provide complete control over flexbox layouts, from container behavior to individual flex item properties. These properties make it easy to create flexible, responsive layouts with proper alignment and distribution of child elements. Use these on flex containers to control their children or on flex items to control their own behavior.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const FlexExample = styled.div(system.flex);
-
-<FlexExample flex={1} justifyContent="center" alignItems="flex-start" />;
-```
-
-<TokenTable rows={getPropRows('flex')} columns={defaultColumns} />