@codecademy/styleguide 79.2.4-alpha.38d1e4.0 → 79.2.4-alpha.9ce37a.0

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

@@ -0,0 +1,352 @@
+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: {
+    description: 'Chart showing programming language experience levels',
+    maxScaleValue: 2000,
+    title: 'Skills experience chart',
+    unit: 'XP',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BarChart>;
+
+const simpleBarData: BarProps[] = [
+  { categoryLabel: 'Python', seriesOneValue: 1500 },
+  { categoryLabel: 'JavaScript', seriesOneValue: 2000 },
+  { categoryLabel: 'HTML/CSS', seriesOneValue: 800 },
+  { categoryLabel: 'SQL', seriesOneValue: 600 },
+  { categoryLabel: 'React', seriesOneValue: 450 },
+];
+
+const stackedBarData: BarProps[] = [
+  { categoryLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    categoryLabel: 'JavaScript',
+    icon: TerminalIcon,
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+  },
+  { categoryLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { categoryLabel: 'SQL', seriesOneValue: 550, seriesTwoValue: 600 },
+  { categoryLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const accessibilityBarData: BarProps[] = [
+  { categoryLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    categoryLabel: 'JavaScript',
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+    href: '/javascript',
+  },
+  { categoryLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { categoryLabel: 'SQL', seriesOneValue: 550, href: '/sql' },
+  { categoryLabel: 'Rust', seriesOneValue: 400 },
+  { categoryLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const accessibilityTranslations: PartialBarChartTranslations = {
+  accessibility: {
+    stackedBarSummary: (ctx) =>
+      `${ctx.seriesOneValue} ${ctx.unit} gained — now at ${ctx.seriesTwoValue} ${ctx.unit} in ${ctx.categoryLabel}`,
+    singleValueBarSummary: (ctx) =>
+      `${ctx.value} ${ctx.unit} in ${ctx.categoryLabel}`,
+  },
+  locale: 'en',
+};
+
+const barDataWithIcons: BarProps[] = [
+  {
+    categoryLabel: 'Python',
+    seriesOneValue: 200,
+    seriesTwoValue: 1500,
+    icon: TerminalIcon,
+  },
+  {
+    categoryLabel: 'JavaScript',
+    seriesOneValue: 150,
+    seriesTwoValue: 2000,
+    icon: TerminalIcon,
+  },
+  {
+    categoryLabel: 'Data Science',
+    seriesOneValue: 100,
+    seriesTwoValue: 800,
+    icon: DataScienceIcon,
+  },
+  {
+    categoryLabel: 'Backend',
+    seriesOneValue: 50,
+    seriesTwoValue: 600,
+    icon: TerminalIcon,
+  },
+  {
+    categoryLabel: '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.categoryLabel}`),
+    })),
+    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.categoryLabel.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
+        maxScaleValue={2000}
+        title="Programming Skills Overview"
+        unit="XP"
+      />
+    );
+  },
+};
+
+export const WithExternalTitle: Story = {
+  render: () => {
+    return (
+      <>
+        <Box
+          as="h2"
+          bg="background-selected"
+          border={1}
+          borderRadius="lg"
+          id="external-chart-title"
+          p={16}
+          textAlign="right"
+        >
+          Programming Skills Overview
+        </Box>
+        <BarChart
+          aria-labelledby="external-chart-title"
+          barValues={simpleBarData}
+          description="Experience points earned across different programming languages"
+          hideDescription={false}
+          maxScaleValue={2000}
+          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 = [
+  {
+    categoryLabel: 'Python',
+    seriesOneValue: 1500,
+    dateAdded: new Date('2023-01-15'),
+  },
+  {
+    categoryLabel: 'JavaScript',
+    seriesOneValue: 2000,
+    dateAdded: new Date('2023-03-20'),
+  },
+  {
+    categoryLabel: 'React',
+    seriesOneValue: 450,
+    dateAdded: new Date('2023-06-10'),
+  },
+  {
+    categoryLabel: 'TypeScript',
+    seriesOneValue: 300,
+    dateAdded: new Date('2023-08-05'),
+  },
+  {
+    categoryLabel: '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) => {
+            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) => {
+            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',
+  },
+};
+
+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',
+  },
+};
+
+export const CustomScale: Story = {
+  args: {
+    barValues: simpleBarData,
+    maxScaleValue: 2000,
+    scaleInterval: 250,
+    title: 'Skills chart with custom scale',
+    description: 'Custom scale intervals for more granular value display',
+  },
+};
+
+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: {
+        stackedBarSummary: (ctx) =>
+          `Valor inicial - ${ctx.seriesOneValue} ${ctx.unit}. ${ctx.gained} ${ctx.unit} ganado - ahora en ${ctx.seriesTwoValue} ${ctx.unit} en ${ctx.categoryLabel}`,
+        singleValueBarSummary: (ctx) =>
+          `${ctx.value} ${ctx.unit} en ${ctx.categoryLabel}`,
+      },
+    },
+  },
+};
+
+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/Meta/Gamut writing guide/About.mdx

@@ -1,43 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import {
-  AboutHeader,
-  addParentPath,
-  LinkTo,
-  TableOfContents,
-} from '~styleguide/blocks';
-
-import { parameters as documentationInCodeParameters } from './Documentation in code.mdx';
-import { parameters as formattingParameters } from './Formatting.mdx';
-import { parameters as generalPrinciplesParameters } from './General principles.mdx';
-import { parameters as languageAndGrammarParameters } from './Language and grammar.mdx';
-import { parameters as linkingParameters } from './Linking.mdx';
-import { parameters as referencingCodeParameters } from './Referencing code.mdx';
-import { parameters as storiesParameters } from './Stories/About.mdx';
-
-export const parameters = {
-  id: 'Meta/Gamut writing guide',
-  title: 'Gamut writing guide',
-  subtitle:
-    'Guidelines and standards for creating consistent, clear, and effective documentation.',
-};
-
-<Meta title="Meta/Gamut writing guide/About" />
-
-<AboutHeader {...parameters} />
-
-Welcome to the Gamut writing guide! Thanks for taking the time to learn about our documentation standards. This guide helps keep our documentation clear, consistent, and useful across the Gamut design system.
-
-The <LinkTo id="Meta/Gamut writing guide/General principles">General principles</LinkTo> is a great place to get an overview of our documentation philosophy and best practices. For specific topics like formatting, code documentation, or writing Storybook stories, check out the other pages below.
-
-<TableOfContents
-  links={addParentPath(parameters.id, [
-    generalPrinciplesParameters,
-    documentationInCodeParameters,
-    formattingParameters,
-    languageAndGrammarParameters,
-    linkingParameters,
-    referencingCodeParameters,
-    storiesParameters,
-  ])}
-/>

package/src/lib/Meta/Gamut writing guide/Documentation in code.mdx

@@ -1,134 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader } from '~styleguide/blocks';
-
-export const parameters = {
-  title: 'Documentation in code',
-  subtitle: `Guidelines for documenting code in Gamut component files`,
-  status: 'static',
-};
-
-<Meta title="Meta/Gamut writing guide/Documentation in code" />
-
-<AboutHeader {...parameters} />
-
-Good documentation starts in the code itself. By documenting components, props, and functions directly in source files, we create a single source of truth that stays synchronized with the implementation and surfaces automatically in developer tools and Storybook.
-
-## Naming conventions
-
-Clear, descriptive names reduce the need for comments and make code self-documenting. Choose names that reveal intent and follow established patterns.
-
-### Variables and constants
-
-- Use `camelCase` for variables: `userName`, `isLoading`, `itemCount`
-- Use descriptive names that reveal purpose: `filteredResults` not `arr`
-- Boolean variables should use `is`, `has`, `should`, or `can` prefixes: `isVisible`, `hasError`, `shouldRender`
-- Use `SCREAMING_SNAKE_CASE` for true constants: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT`
-- Avoid single-letter names except for short loops or mathematical operations
-- Use plural names for arrays and collections: `users`, `menuItems`
-
-### Functions and methods
-
-- Use `camelCase` for function names: `getUserData`, `calculateTotal`, `handleClick`
-- Start with verbs that describe the action: `get`, `set`, `fetch`, `handle`, `render`, `calculate`
-- Event handlers should use `handle` prefix: `handleSubmit`, `handleClickOutside`
-- Boolean-returning functions should ask a question: `isValidEmail`, `canAccessResource`, `hasPermission`
-- Keep names concise but descriptive: `fetchUserProfile` not `getUserProfileDataFromAPI`
-
-### Components
-
-- Use `PascalCase` for component names: `Button`, `UserProfile`, `NavigationMenu`
-- Name folders to match the component: `Button`, `UserProfile`
-  - Subsequently, name files within the folder to match the component: `Button.tsx`, `UserProfile.tsx`
-- Use descriptive names that indicate purpose: `SkipToContent`, `RadialProgress`, `Toggle`
-- Avoid generic names like `Component`, `Container`, `Wrapper` without context
-
-## Code comments
-
-Comments should explain _why_ code exists, not _what_ it does. Well-named variables and functions handle the "what." Reserve comments for non-obvious decisions, complex logic, and important context.
-
-### When to comment
-
-- **Complex logic**: Explain algorithms or non-obvious implementations
-
-  ```tsx
-  // Use binary search for O(log n) performance on sorted arrays
-  const index = binarySearch(sortedArray, target);
-  ```
-
-- **Business logic**: Document requirements or constraints
-
-  ```tsx
-  // Per WCAG 2.2, focus must return to trigger element on close
-  previousFocusRef.current?.focus();
-  ```
-
-- **Workarounds**: Explain temporary fixes or browser-specific code
-
-  ```tsx
-  // Safari doesn't support :focus-visible, fallback to :focus
-  // TODO: Remove when Safari 15+ is minimum supported version
-  ```
-
-- **Non-obvious decisions**: Clarify choices that might seem strange
-  ```tsx
-  // Delay state update to avoid race condition with async validation
-  setTimeout(() => setIsValid(true), 0);
-  ```
-
-### When NOT to comment
-
-- **Self-explanatory code**: Good names eliminate the need
-
-  ```tsx
-  // ❌ Bad: Comment restates the code
-  // Set loading to true
-  setIsLoading(true);
-
-  // ✅ Good: Code is self-documenting
-  setIsLoading(true);
-  ```
-
-- **Commented-out code**: Delete it; Git tracks history
-  ```tsx
-  // ❌ Bad: Dead code clutters the file
-  // const oldImplementation = () => { ... };
-  ```
-
-### Comment style
-
-- Use `//` for single-line comments, add a space after the `//` before commenting
-- Use `/** */` for JSDoc comments on exports (functions, types, components)
-- Write complete sentences with proper punctuation
-- Keep comments up-to-date when code changes
-
-## API reference
-
-Well-documented APIs make components easier to use and understand. Clear prop descriptions and type information help developers implement components correctly without needing to read the source code.
-
-### Props documentation:
-
-Add [JSDoc](https://jsdoc.app/) comments to the props to provide additional clarity for what these props do — these comments is used by TypeScript when hovering over a prop, additional it also shows up in the props table of a component's story in Storybook.
-
-```tsx
-export type ButtonProps = {
-  /**
-   * The visual style variant of the button.
-   */
-  variant: 'primary' | 'secondary';
-
-  /**
-   * Whether the button is disabled.
-   */
-  disabled?: boolean;
-};
-```
-
-### Guidelines:
-
-- Use full sentence descriptions
-- Start boolean descriptions with "Whether"
-- Document required vs. optional props
-- Include type information
-- Use discretion for whether a comment is needed or not
-  - If unsure, include a comment

package/src/lib/Meta/Gamut writing guide/Formatting.mdx

@@ -1,69 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader } from '~styleguide/blocks';
-
-export const parameters = {
-  id: 'Formatting',
-  title: 'Formatting',
-  subtitle: 'Standards for formatting text and content in documentation',
-  status: 'static',
-};
-
-<Meta title="Meta/Gamut writing guide/Formatting" />
-
-<AboutHeader {...parameters} />
-
-Consistent formatting makes documentation easier to scan, understand, and implement. These standards ensure our content is predictable and professional across all Gamut components.
-
-## Numbers
-
-- Use numerals for all numbers
-- Use commas for thousands: 1,000
-
-## Units of Measurement
-
-- Use standard units: px, rem, em, %
-- Include space between number and unit in prose: "16 pixels"
-- No space in code: `16px`, `2rem`
-
-## Lists
-
-Lists help break down complex information into digestible pieces. Use them to organize features, steps, or related concepts.
-
-### Bulleted lists:
-
-- Use for unordered items
-- Use parallel structure
-- End with periods if items are complete sentences
-- No periods if items are fragments
-
-### Numbered lists:
-
-- Use for sequential steps or prioritized items
-- Start each item with a capital letter
-
-## Code Blocks
-
-- Use triple backticks (` ``` `) with language identifier (e.g., `tsx`, `javascript`, `css`)
-- Include comments for complex examples
-- Keep examples concise and focused
-
-Example:
-
-````
-```tsx
-<TextButton onClick={handleClick}> Click me </TextButton>
-```
-````
-
-## Headings Hierarchy
-
-- Start with second-level headings (`<h2>` in HTML, `##` in Markdown). The first level heading is automatically set by the title parameter.
-- Don't skip heading levels. This ensures a logical reading order.
-
-## Whitespace
-
-- Use blank lines to separate sections
-- Don't use multiple consecutive blank lines
-- Indent code consistently (2 spaces for TypeScript/TSX)
-  - When using tabs, set them to 2 spaces

package/src/lib/Meta/Gamut writing guide/General principles.mdx

@@ -1,46 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader } from '~styleguide/blocks';
-
-export const parameters = {
-  id: 'General principles',
-  title: 'General principles',
-  subtitle: 'Core principles for writing effective documentation',
-  status: 'static',
-};
-
-<Meta title="Meta/Gamut writing guide/General principles" />
-
-<AboutHeader {...parameters} />
-
-Good documentation does more than describe—it helps people succeed. These principles guide how we write about Gamut components, with a focus on clarity, accessibility, and helpfulness. Whether documenting a new component or updating existing content, prioritize being clear about what something does and honest about its limitations, accessible to the users who will interact with it, and helpful in showing how to use it effectively. We want to remove barriers and make it easier for designers and developers to do great work. Like our design system itself, this guide is a living document—it will continue to evolve as we add new features and learn from our users.
-
-## Voice and tone
-
-- Friendly and conversational: Write as if explaining to a colleague
-- Prefer "we" when a pronoun is needed
-  - "You" is acceptable when necessary, e.g., "Use your best judgement"
-- Encouraging without overpromising: Be supportive but realistic
-- Global audience awareness: Avoid idioms, slang, and culturally-specific references
-
-## Inclusivity
-
-- Use inclusive language that makes all contributors feel welcome
-- Define terms when first introduced
-- Consider contributors of varying experience levels and roles (designers and developers)
-
-## Transparency
-
-- Clearly indicate component status:
-  - `current`: Stable, recommended for use
-  - `updating`: In progress, API may change
-  - `deprecated`: Still supported but slated for deletion — do not use for new work
-  - `static`: Reference material, no active development
-- Link to source code and design files (GitHub, Figma)
-
-## Consistency
-
-- Use a single term for the same concept, including how it's referred to between the heading, body copy, and code examples.
-- Do not use the same term for 2 different concepts.
-- Maintain consistent component naming across packages
-- Follow established patterns from existing components

package/src/lib/Meta/Gamut writing guide/Language and grammar.mdx

@@ -1,54 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader } from '~styleguide/blocks';
-
-export const parameters = {
-  id: 'Language and grammar',
-  title: 'Language and grammar',
-  subtitle: 'Guidelines for language usage and grammar in documentation',
-  status: 'static',
-};
-
-<Meta title="Meta/Gamut writing guide/Language and grammar" />
-
-<AboutHeader {...parameters} />
-
-## Voice
-
-Use active voice rather than passive voice — it makes clear who should do what and eliminates ambiguity about responsibilities. Passive voice obscures who handles what and makes documentation harder to follow. E.g. "The component renders..." not "The component is rendered by..."
-
-Use imperative mood for instructions: "Add the component" not "You should add the component"
-
-## Tense
-
-Use present tense for current functionality — it's the simplest and most direct form of a verb, making writing more clearer. The more conditional or future tense is used, the harder the audience has to work to understand the meaning. E.g. "The `StrokeButton` component accepts a `variant` prop."
-
-- Use future tense sparingly, only for confirmed features
-- Avoid past tense except in changelogs or historical context
-
-## Pronouns
-
-With active voice and imperative mood, we can often forgo pronouns entirely. However, if a pronoun is still necessary, consider these rules:
-
-- Prefer "we" when a pronoun is needed
-  - "You" is acceptable when necessary, e.g., "Use your best judgement"
-- Avoid "I/my/me" entirely
-
-## Articles
-
-- Use articles (a, an, the) for clarity
-- Omit articles in lists when appropriate for brevity
-
-## Abbreviations and Acronyms
-
-- Spell out on first use: "Web Content Accessibility Guidelines (WCAG)"
-- Use abbreviations for common terms in the domain of web design and development:
-  - HTML, CSS, API, UI, UX, etc.
-- Avoid uncommon abbreviations without definition
-
-## Capitalization
-
-- Sentence case for all headings, buttons, and UI text
-- PascalCase for component names: `MyComponent`, `ButtonGroup`
-- camelCase for props and variables: `onClick`, `backgroundColor`
-- Capitalize proper nouns: Codecademy, Storybook, Figma, GitHub