@codecademy/styleguide 79.1.5-alpha.a28b9a.0 → 79.1.5-alpha.b03ce1.0

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-### [79.1.5-alpha.a28b9a.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.4...@codecademy/styleguide@79.1.5-alpha.a28b9a.0) (2026-03-10)
+### [79.1.5-alpha.b03ce1.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.4...@codecademy/styleguide@79.1.5-alpha.b03ce1.0) (2026-03-12)
 
 **Note:** Version bump only for package @codecademy/styleguide
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.1.5-alpha.a28b9a.0",
+  "version": "79.1.5-alpha.b03ce1.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "b3069e30414f20b84c57803fd94a191c03b9e575"
+  "gitHead": "d03a4c2d4b5dd73e45d990f755ba3ca2366f9ce5"
 }

package/src/lib/Organisms/BarChart/BarChart.mdx

@@ -271,11 +271,11 @@ If `styleConfig` is not provided, BarChart uses these default colors:
 
 ## Custom scale
 
-BarChart allows you to customize the x-axis scale interval using the `xScale` prop, which controls the spacing and granularity of scale markers along the horizontal axis.
+BarChart allows you to customize the x-axis scale interval using the `scaleInterval` prop, which controls the spacing and granularity of scale markers along the horizontal axis.
 
 ### Scale configuration
 
-The `xScale` prop determines the interval between scale markers on the x-axis. By default, BarChart automatically calculates an appropriate scale interval based on the `maxRange` value (the scale always starts at 0). However, you can override this with a custom interval to achieve more granular or specific scale markings.
+The `scaleInterval` prop determines the interval between scale markers on the x-axis. By default, BarChart automatically calculates an appropriate scale interval based on the `maxScaleValue` value (the scale always starts at 0). However, you can override this with a custom interval to achieve more granular or specific scale markings.
 
 **When to use custom scale:**
 
@@ -286,12 +286,12 @@ The `xScale` prop determines the interval between scale markers on the x-axis. B
 
 **How it works:**
 
-The `xScale` value represents the interval between consecutive scale markers. For example:
+The `scaleInterval` value represents the interval between consecutive scale markers. For example:
 
-- `xScale: 250` creates markers at 0, 250, 500, 750, 1000, etc.
-- `xScale: 500` creates markers at 0, 500, 1000, 1500, 2000, etc.
+- `scaleInterval: 250` creates markers at 0, 250, 500, 750, 1000, etc.
+- `scaleInterval: 500` creates markers at 0, 500, 1000, 1500, 2000, etc.
 
-The number of tick marks is automatically calculated as: `Math.ceil(maxRange / xScale) + 1`
+The number of tick marks is automatically calculated as: `Math.ceil(maxScaleValue / scaleInterval) + 1`
 
 ### Example
 
@@ -347,9 +347,67 @@ BarChart supports internationalization through the `translations` prop. You can
 ### Translation structure
 
 - **sortLabel**, **sortOptions**, and **locale** — Always strings. Control the sort dropdown label, option labels, and number-formatting locale.
-- **Accessibility keys** (`gainedNowAt`, `inLabel`, `inOnly`) — Used in auto-generated `aria-label` and screen reader text for bars. Each key can be:
-  - **String** — A fragment interpolated into the built-in template (e.g. `"in"`, `"gained - now at"`). Use when the default word order works for your language.
-  - **Function** — Receives scoped context (values, label, unit, locale) and returns the **entire** summary string. Use for pluralization, different word order, or locale-specific phrasing.
+- **Accessibility** — Two optional summary functions; when omitted, default English summaries are used. Each function receives context and returns the full summary string.
+  - **stackedBarSummary** — Used for stacked (two-value) rows. Context includes `seriesOneValue`, `seriesTwoValue`, **gained** (seriesTwoValue - seriesOneValue), `unit`, `locale`, `categoryLabel`.
+  - **singleValueBarSummary** — Used for all single-value rows. Context includes `value`, `unit`, `locale`, `categoryLabel`.
+
+### Where accessibility summaries appear
+
+Each bar row gets one summary from either `stackedBarSummary` (stacked rows) or `singleValueBarSummary` (single-value rows). That string is then exposed as **`aria-label`** on the row's link or button when the row is interactive, or as **screenreader-only text** (visually hidden) when the row is not interactive.
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Used for</th>
+      <th>Context (props)</th>
+      <th>Default English interpolation</th>
+      <th>Summary exposed as</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>stackedBarSummary</code>
+      </td>
+      <td>Stacked rows (two values per row)</td>
+      <td>
+        <code>seriesOneValue</code>, <code>seriesTwoValue</code>,{' '}
+        <code>gained</code>, <code>unit</code>, <code>locale</code>,{' '}
+        <code>categoryLabel</code>
+      </td>
+      <td>
+        <code>
+          Starting value - &#123;seriesOneValue&#125;&#123;unit&#125;.
+          &#123;gained&#125;&#123;unit&#125; gained - now at
+          &#123;seriesTwoValue&#125;&#123;unit&#125; in
+          &#123;categoryLabel&#125;
+        </code>
+      </td>
+      <td>
+        <code>aria-label</code> (if link/button) or screenreader-only text
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>singleValueBarSummary</code>
+      </td>
+      <td>Single-value rows</td>
+      <td>
+        <code>value</code>, <code>unit</code>, <code>locale</code>,{' '}
+        <code>categoryLabel</code>
+      </td>
+      <td>
+        <code>
+          &#123;value&#125;&#123;unit&#125; in &#123;categoryLabel&#125;
+        </code>
+      </td>
+      <td>
+        <code>aria-label</code> (if link/button) or screenreader-only text
+      </td>
+    </tr>
+  </tbody>
+</table>
 
 ### Basic usage
 
@@ -359,14 +417,15 @@ Provide only the translations you want to override; the rest fall back to defaul
 <BarChart
   barValues={barData}
   description="Progreso de habilidades"
-  maxRange={200}
+  maxScaleValue={200}
   sortFns={['alphabetically', 'none']}
   title="Habilidades"
   translations={{
     accessibility: {
-      gainedNowAt: 'ganado - ahora en',
-      inLabel: 'en',
-      inOnly: 'en ',
+      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}`,
     },
     locale: 'es',
     sortLabel: 'Ordenar por:',
@@ -398,18 +457,11 @@ translations={{
 }}
 ```
 
-### Accessibility: strings vs functions
-
-**Strings** — Use when the built-in template order fits your language. Fragments are plugged into the default pattern (e.g. `"{value} {unit} {inLabel} {categoryLabel}"`).
-
-**Functions** — Use when you need full control. Each function receives context (`categoryLabel`, values, `unit`, `locale`) and returns the complete summary string.
-
 <Canvas of={BarChartStories.WithFunctionTranslations} />
 
 **Best practices:**
 
-- Provide complete translations for the language your app uses; use partial overrides for one-off changes.
-- Prefer string accessibility keys when the default order works; use functions for pluralization, word order, or locale-specific phrasing.
+- Provide summary functions for the locales your app uses; use default behavior when the default English is acceptable.
 - Use appropriate locale codes (e.g. `'en-US'`, `'es-ES'`, `'fr-FR'`) for number formatting.
 - Test accessibility summaries with screen readers in the target language.
 - Reuse translation objects across BarChart instances where possible.

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

@@ -16,7 +16,7 @@ const meta: Meta<typeof BarChart> = {
   component: BarChart,
   args: {
     description: 'Chart showing programming language experience levels',
-    maxRange: 2000,
+    maxScaleValue: 2000,
     title: 'Skills experience chart',
     unit: 'XP',
   },
@@ -62,10 +62,10 @@ const accessibilityBarData: BarProps[] = [
 
 const accessibilityTranslations: PartialBarChartTranslations = {
   accessibility: {
-    gainedNowAt: (ctx) =>
+    stackedBarSummary: (ctx) =>
       `${ctx.seriesOneValue} ${ctx.unit} gained — now at ${ctx.seriesTwoValue} ${ctx.unit} in ${ctx.categoryLabel}`,
-    inLabel: (ctx) => `${ctx.value} ${ctx.unit} in ${ctx.categoryLabel}`,
-    inOnly: (ctx) => `${ctx.value} ${ctx.unit}`.trim(),
+    singleValueBarSummary: (ctx) =>
+      `${ctx.value} ${ctx.unit} in ${ctx.categoryLabel}`,
   },
   locale: 'en',
 };
@@ -175,7 +175,7 @@ export const WithHiddenTitleAndDescription: Story = {
         description="Experience points earned across different programming languages"
         hideDescription
         hideTitle
-        maxRange={2000}
+        maxScaleValue={2000}
         title="Programming Skills Overview"
         unit="XP"
       />
@@ -199,11 +199,11 @@ export const WithExternalTitle: Story = {
           Programming Skills Overview
         </Box>
         <BarChart
-          aria-labelledby="external-title"
+          aria-labelledby="external-chart-title"
           barValues={simpleBarData}
           description="Experience points earned across different programming languages"
           hideDescription={false}
-          maxRange={2000}
+          maxScaleValue={2000}
           unit="XP"
         />
       </>
@@ -306,8 +306,8 @@ export const CustomStyles: Story = {
 export const CustomScale: Story = {
   args: {
     barValues: simpleBarData,
-    maxRange: 2000,
-    xScale: 250,
+    maxScaleValue: 2000,
+    scaleInterval: 250,
     title: 'Skills chart with custom scale',
     description: 'Custom scale intervals for more granular value display',
   },
@@ -331,9 +331,10 @@ export const WithStringTranslations: Story = {
         valueDesc: 'Valor (Alto-Bajo)',
       },
       accessibility: {
-        gainedNowAt: 'ganado - ahora en',
-        inLabel: 'en',
-        inOnly: 'en ',
+        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}`,
       },
     },
   },