@codecademy/styleguide 79.0.1-alpha.4aeb6d.0 → 79.0.1-alpha.5950e5.0

package/src/lib/Organisms/BarChart/BarChart.stories.tsx

@@ -0,0 +1,378 @@
+import {
+  BarChart,
+  BarProps,
+  Box,
+  PartialBarChartTranslations,
+} from '@codecademy/gamut';
+import {
+  BookFlipPageIcon,
+  DataScienceIcon,
+  TerminalIcon,
+} from '@codecademy/gamut-icons';
+import { action } from '@storybook/addon-actions';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof BarChart> = {
+  component: BarChart,
+  args: {
+    title: 'Skills experience chart',
+    description: 'Chart showing programming language experience levels',
+    minRange: 0,
+    maxRange: 2000,
+    unit: 'XP',
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'BarChart supports i18n via the `translations` prop. Accessibility keys (`gainedNowAt`, `inLabel`, `inOnly`) may be strings (fragments in the built-in template) or functions that receive scoped context (values, label, unit, locale) and return the full accessibility summary—useful for pluralization, word order, or locale-specific phrasing.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BarChart>;
+
+const simpleBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 1500 },
+  { yLabel: 'JavaScript', seriesOneValue: 2000 },
+  { yLabel: 'HTML/CSS', seriesOneValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 600 },
+  { yLabel: 'React', seriesOneValue: 450 },
+];
+
+const stackedBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    yLabel: 'JavaScript',
+    icon: TerminalIcon,
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+  },
+  { yLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 550, seriesTwoValue: 600 },
+  { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const accessibilityBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+    href: '/javascript',
+  },
+  { yLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 550, href: '/sql' },
+  { yLabel: 'Rust', seriesOneValue: 400 },
+  { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const accessibilityTranslations: PartialBarChartTranslations = {
+  accessibility: {
+    gainedNowAt: (ctx) =>
+      `${ctx.seriesOneValue} ${ctx.unit} gained — now at ${ctx.seriesTwoValue} ${ctx.unit} in ${ctx.yLabel}`,
+    inLabel: (ctx) => `${ctx.value} ${ctx.unit} in ${ctx.yLabel}`,
+    inOnly: (ctx) => `${ctx.value} ${ctx.unit}`.trim(),
+  },
+  locale: 'en',
+};
+
+const barDataWithIcons: BarProps[] = [
+  {
+    yLabel: 'Python',
+    seriesOneValue: 200,
+    seriesTwoValue: 1500,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 150,
+    seriesTwoValue: 2000,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'Data Science',
+    seriesOneValue: 100,
+    seriesTwoValue: 800,
+    icon: DataScienceIcon,
+  },
+  {
+    yLabel: 'Backend',
+    seriesOneValue: 50,
+    seriesTwoValue: 600,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'Reading',
+    seriesOneValue: 75,
+    seriesTwoValue: 450,
+    icon: BookFlipPageIcon,
+  },
+];
+
+export const Default: Story = {
+  args: {
+    barValues: simpleBarData,
+    title: 'Skills experience chart',
+    description: 'Chart showing programming language experience levels',
+  },
+};
+
+export const Stacked: Story = {
+  args: {
+    barValues: stackedBarData,
+    title: 'Skills progress chart',
+    description: 'Progress toward total goals for each programming language',
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    barValues: barDataWithIcons,
+    title: 'Skills progress with icons',
+    description: 'Skills progress with visual icons for each category',
+  },
+};
+
+export const Animated: Story = {
+  args: {
+    barValues: stackedBarData,
+    animate: true,
+    title: 'Animated skills chart',
+    description: 'Animated chart showing progress with entrance animations',
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      onClick: action(`Clicked ${bar.yLabel}`),
+    })),
+    title: 'Interactive skills chart',
+    description: 'Click on any row to view detailed course information',
+  },
+};
+
+export const WithLinks: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      href: `#${bar.yLabel.toLowerCase().replace(/\s+/g, '-')}`,
+    })),
+    title: 'Skills chart with links',
+    description: 'Each row links to its corresponding course page',
+  },
+};
+
+export const WithVisualTitleAndDescription: Story = {
+  args: {
+    barValues: simpleBarData,
+    title: 'Programming Skills Overview',
+    description:
+      'Experience points earned across different programming languages',
+  },
+};
+
+export const WithHiddenTitleAndDescription: Story = {
+  render: () => {
+    return (
+      <BarChart
+        barValues={simpleBarData}
+        description="Experience points earned across different programming languages"
+        hideDescription
+        hideTitle
+        maxRange={2000}
+        minRange={0}
+        title="Programming Skills Overview"
+        unit="XP"
+      />
+    );
+  },
+};
+
+export const WithExternalTitle: Story = {
+  render: () => {
+    return (
+      <>
+        <Box
+          as="h2"
+          bg="paleBlue"
+          border={1}
+          borderRadius="lg"
+          id="external-chart-title"
+          p={16}
+          textAlign="right"
+        >
+          Programming Skills Overview
+        </Box>
+        <BarChart
+          aria-labelledby="external-title"
+          barValues={simpleBarData}
+          description="Experience points earned across different programming languages"
+          hideDescription={false}
+          maxRange={2000}
+          minRange={0}
+          unit="XP"
+        />
+      </>
+    );
+  },
+};
+
+export const WithSorting: Story = {
+  args: {
+    barValues: simpleBarData,
+    sortFns: ['alphabetically', 'numerically', 'none'],
+    title: 'Skills experience chart',
+    description: 'Use the dropdown to sort bars by different criteria',
+  },
+};
+
+const customSortingBarValues = [
+  {
+    yLabel: 'Python',
+    seriesOneValue: 1500,
+    dateAdded: new Date('2023-01-15'),
+  },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 2000,
+    dateAdded: new Date('2023-03-20'),
+  },
+  {
+    yLabel: 'React',
+    seriesOneValue: 450,
+    dateAdded: new Date('2023-06-10'),
+  },
+  {
+    yLabel: 'TypeScript',
+    seriesOneValue: 300,
+    dateAdded: new Date('2023-08-05'),
+  },
+  {
+    yLabel: 'SQL',
+    seriesOneValue: 600,
+    dateAdded: new Date('2023-02-28'),
+  },
+];
+
+export const WithCustomSorting: Story = {
+  args: {
+    barValues: customSortingBarValues,
+    sortFns: [
+      'none',
+      {
+        label: 'Recently Added',
+        value: 'recent',
+        sortFn: (bars) => {
+          return [...bars].sort((a, b) => {
+            // TypeScript infers the type from barValues, so dateAdded is properly typed
+            const aDate = a.dateAdded as Date | undefined;
+            const bDate = b.dateAdded as Date | undefined;
+            if (!aDate && !bDate) return 0;
+            if (!aDate) return 1;
+            if (!bDate) return -1;
+            return bDate.getTime() - aDate.getTime();
+          });
+        },
+      },
+      {
+        label: 'Oldest First',
+        value: 'oldest',
+        sortFn: (bars) => {
+          return [...bars].sort((a, b) => {
+            // TypeScript infers the type from barValues, so dateAdded is properly typed
+            const aDate = a.dateAdded as Date | undefined;
+            const bDate = b.dateAdded as Date | undefined;
+            if (!aDate && !bDate) return 0;
+            if (!aDate) return 1;
+            if (!bDate) return -1;
+            return aDate.getTime() - bDate.getTime();
+          });
+        },
+      },
+    ],
+    title: 'Skills chart with date sorting',
+    description:
+      'Custom sort functions can access additional properties on BarProps, such as dates',
+  },
+};
+
+/**
+ * Bar chart with custom styling
+ */
+export const CustomStyles: Story = {
+  args: {
+    barValues: stackedBarData,
+    styleConfig: {
+      seriesTwoBarColor: 'text',
+      seriesOneBarColor: 'primary',
+      textColor: 'primary',
+      seriesOneLabel: 'feedback-error',
+      seriesTwoLabel: 'feedback-success',
+    },
+    title: 'Custom styled skills chart',
+    description: 'Custom color scheme applied to chart elements',
+  },
+};
+
+/**
+ * Bar chart with custom xScale interval
+ */
+export const CustomScale: Story = {
+  args: {
+    barValues: simpleBarData,
+    maxRange: 2000,
+    xScale: 250,
+    title: 'Skills chart with custom scale',
+    description: 'Custom scale intervals for more granular value display',
+  },
+};
+
+/**
+ * Bar chart with string-based translations (e.g. Spanish).
+ * Partial translations are merged with defaults.
+ */
+export const WithStringTranslations: Story = {
+  args: {
+    barValues: stackedBarData,
+    sortFns: ['alphabetically', 'numerically', 'none'],
+    title: 'Gráfico de habilidades',
+    description: 'Progreso hacia los objetivos totales por lenguaje',
+    unit: 'XP',
+    translations: {
+      locale: 'es',
+      sortLabel: 'Ordenar por:',
+      sortOptions: {
+        none: 'Ninguno',
+        labelAsc: 'Etiqueta (A-Z)',
+        labelDesc: 'Etiqueta (Z-A)',
+        valueAsc: 'Valor (Bajo-Alto)',
+        valueDesc: 'Valor (Alto-Bajo)',
+      },
+      accessibility: {
+        gainedNowAt: 'ganado - ahora en',
+        inLabel: 'en',
+        inOnly: 'en ',
+      },
+    },
+  },
+};
+
+/**
+ * Bar chart with function-based accessibility translations.
+ * Exercises gainedNowAt (stacked), inLabel (link/button single bar), and inOnly (non-interactive single bar).
+ */
+export const WithFunctionTranslations: Story = {
+  args: {
+    barValues: accessibilityBarData,
+    description:
+      'Custom aria-label summaries via translation functions (stacked, link, and non-interactive bars)',
+    title: 'Skills experience (accessibility functions)',
+    translations: accessibilityTranslations,
+    unit: 'XP',
+  },
+};

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,53 +0,0 @@
-import { Canvas, Meta } from '@storybook/blocks';
-
-import { AboutHeader, Callout, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../../shared/elements';
-import * as BorderStories from './Border.stories';
-
-export const parameters = {
-  title: 'Border',
-  subtitle: 'Border styles',
-  status: 'updating',
-};
-
-<Meta of={BorderStories} 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"
-/>;
-```
-
-These border props support both physical and logical CSS properties and will render the appropriate properties based on `useLogicalProperties`'s value passed into the `<GamutProvider>` at the root of your application.
-
-<Callout
-  text={
-    <>
-      You can use the <strong>LogicalProps</strong> button in the toolbar to
-      switch between modes.
-    </>
-  }
-/>
-
-<Canvas of={BorderStories.DirectionalBorderExample} />
-
-<Canvas of={BorderStories.BorderWidthExample} />
-
-<Canvas of={BorderStories.BorderRadiusExample} />
-
-<Canvas of={BorderStories.BorderStyleExample} />
-
-<TokenTable rows={getPropRows('border')} columns={defaultColumns} />

package/src/lib/Foundations/System/Props/Border.stories.tsx

@@ -1,138 +0,0 @@
-import { Box, FlexBox, Markdown } from '@codecademy/gamut';
-import type { Meta, StoryObj } from '@storybook/react';
-
-const meta: Meta<typeof Box> = {
-  title: 'Foundations/System/Props/Border',
-  component: Box,
-};
-
-export default meta;
-type Story = StoryObj<typeof Box>;
-
-export const DirectionalBorderExample: Story = {
-  render: () => (
-    <FlexBox gap={16} row>
-      <Box
-        bg="background-selected"
-        borderX={2}
-        borderY={1}
-        p={16}
-        textAlign="center"
-      >
-        This box has <Markdown text="`borderX={2}`, `borderY={1}`." /> Inspect
-        the example to see what CSS properties are rendered based on the logical
-        properties mode.
-      </Box>
-      <Box
-        bg="background-selected"
-        borderLeft={2}
-        borderRight={1}
-        p={16}
-        textAlign="center"
-      >
-        This box has <Markdown text="`borderLeft={2}`, `borderRight={1}`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-    </FlexBox>
-  ),
-};
-
-export const BorderWidthExample: Story = {
-  render: () => (
-    <FlexBox gap={16} row>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderWidthX="4px"
-        borderWidthY="10px"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderWidthX='4px'` and `borderWidthY='10px'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderWidthRight="10px"
-        borderWidthTop="4px"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderWidthTop='4px'` and `borderWidthRight='10px'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-    </FlexBox>
-  ),
-};
-
-export const BorderRadiusExample: Story = {
-  render: () => (
-    <FlexBox gap={16} row>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderRadiusLeft="lg"
-        borderRadiusRight="none"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderRadiusLeft='lg'` and `borderRadiusRight='none'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderRadiusBottomLeft="xl"
-        borderRadiusTopRight="xl"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderRadiusTopRight='xl'` and `borderRadiusBottomLeft='xl'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-    </FlexBox>
-  ),
-};
-
-export const BorderStyleExample: Story = {
-  render: () => (
-    <FlexBox gap={16} row>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderStyleX="dashed"
-        borderStyleY="dotted"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderStyleX='dashed'` and `borderStyleY='dotted'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-      <Box
-        bg="background-selected"
-        border={1}
-        borderStyleBottom="dotted"
-        borderStyleLeft="dashed"
-        p={16}
-        textAlign="center"
-      >
-        This box has{' '}
-        <Markdown text="`borderStyleBottom='dotted'` and `borderStyleLeft='dashed'`." />{' '}
-        Inspect the example to see what CSS properties are rendered based on the
-        logical properties mode.
-      </Box>
-    </FlexBox>
-  ),
-};