@codecademy/styleguide 79.1.4-alpha.7f2ebb.0 → 79.1.4-alpha.d3a516.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.4-alpha.7f2ebb.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.3...@codecademy/styleguide@79.1.4-alpha.7f2ebb.0) (2026-03-03)
+### [79.1.4-alpha.d3a516.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.3...@codecademy/styleguide@79.1.4-alpha.d3a516.0) (2026-03-17)
 
 **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.4-alpha.7f2ebb.0",
+  "version": "79.1.4-alpha.d3a516.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "4b12a3262dccac571df2ca18f42df87ad5903a36"
+  "gitHead": "0b2a5f824b8f2ce009e7171b3865bfd2621f60cb"
 }

package/src/lib/Molecules/DatePicker/Calendar.mdx

@@ -0,0 +1,26 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks';
+
+import { ComponentHeader } from '~styleguide/blocks';
+
+import * as CalendarStories from './Calendar.stories';
+
+export const parameters = {
+  title: 'DatePicker/Calendar',
+  subtitle: `Calendar grid with header (month/year + prev/next), body (day grid), and footer (Clear, Today, quick actions). Used inside DatePickerCalendar.`,
+  status: 'current',
+  source: {
+    repo: 'gamut',
+    githubLink:
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/DatePicker/Calendar',
+  },
+};
+
+<Meta of={CalendarStories} />
+
+<ComponentHeader {...parameters} />
+
+## Playground
+
+<Canvas sourceState="shown" of={CalendarStories.Default} />
+
+<Controls />

package/src/lib/Molecules/DatePicker/Calendar.stories.tsx

@@ -0,0 +1,53 @@
+import {
+  Calendar,
+  CalendarBody,
+  CalendarFooter,
+  CalendarHeader,
+} from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+import { useId, useState } from 'react';
+
+const meta: Meta<typeof Calendar> = {
+  component: Calendar,
+  title: 'Molecules/DatePicker/Calendar',
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Calendar>;
+
+export const Default: Story = {
+  render: function CalendarStory() {
+    const headingId = useId();
+    const [visibleDate, setVisibleDate] = useState(() => new Date());
+    const [selectedDate, setSelectedDate] = useState<Date | null>(null);
+    const [focusedDate, setFocusedDate] = useState<Date | null>(
+      () => new Date()
+    );
+
+    return (
+      <Calendar>
+        <CalendarHeader
+          currentMonthYear={visibleDate}
+          headingId={headingId}
+          locale="en-US"
+          onCurrentMonthYearChange={setVisibleDate}
+        />
+        <CalendarBody
+          focusedDate={focusedDate}
+          labelledById={headingId}
+          locale="en-US"
+          selectedDate={selectedDate}
+          visibleDate={visibleDate}
+          onDateSelect={setSelectedDate}
+          onFocusedDateChange={setFocusedDate}
+          onVisibleDateChange={setVisibleDate}
+        />
+        <CalendarFooter
+          onCurrentMonthYearChange={setVisibleDate}
+          onSelectedDateChange={setSelectedDate}
+        />
+      </Calendar>
+    );
+  },
+};

package/src/lib/Molecules/DatePicker/DatePicker.stories.tsx

@@ -0,0 +1,124 @@
+import {
+  Box,
+  DatePicker,
+  DatePickerCalendar,
+  DatePickerInput,
+  PopoverContainer,
+  useDatePicker,
+} from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+import { useRef, useState } from 'react';
+
+const meta: Meta<typeof DatePicker> = {
+  component: DatePicker,
+  title: 'Molecules/DatePicker/DatePicker',
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DatePicker>;
+
+export const Default: Story = {
+  render: function DatePickerStory() {
+    const [selectedDate, setSelectedDate] = useState<Date | null>(null);
+    return (
+      <Box p={32}>
+        <DatePicker
+          label="Date"
+          locale="de-DE"
+          placeholder="MM/DD/YYYY"
+          selectedDate={selectedDate}
+          setSelectedDate={setSelectedDate}
+        />
+      </Box>
+    );
+  },
+};
+
+export const WithInitialDate: Story = {
+  render: function DatePickerStory() {
+    const [selectedDate, setSelectedDate] = useState<Date | null>(
+      () => new Date(2026, 1, 15)
+    );
+    return (
+      <DatePicker
+        label="Date"
+        placeholder="MM/DD/YYYY"
+        selectedDate={selectedDate}
+        setSelectedDate={setSelectedDate}
+      />
+    );
+  },
+};
+
+/** Range mode: two inputs for start and end date. First calendar click sets start, second sets end. */
+export const Range: Story = {
+  render: function DatePickerStory() {
+    const [startDate, setStartDate] = useState<Date | null>(null);
+    const [endDate, setEndDate] = useState<Date | null>(null);
+    return (
+      <Box p={32}>
+        <DatePicker
+          endDate={endDate}
+          endLabel="End date"
+          mode="range"
+          setEndDate={setEndDate}
+          setStartDate={setStartDate}
+          startDate={startDate}
+          startLabel="Start date"
+        />
+      </Box>
+    );
+  },
+};
+
+/**
+ * Composed usage: DatePicker with children provides shared state via context.
+ * The child uses useDatePicker() to get open/close and inputRef, then composes
+ * DatePickerInput and DatePickerCalendar with a custom PopoverContainer layout.
+ */
+export const ComposedWithContext: Story = {
+  render: function DatePickerStory() {
+    const [selectedDate, setSelectedDate] = useState<Date | null>(null);
+    return (
+      <Box p={32}>
+        <DatePicker
+          label="Start date"
+          placeholder="MM/DD/YYYY"
+          selectedDate={selectedDate}
+          setSelectedDate={setSelectedDate}
+        >
+          <ComposedDatePickerLayout />
+        </DatePicker>
+      </Box>
+    );
+  },
+};
+
+function ComposedDatePickerLayout() {
+  const { isCalendarOpen, openCalendar, closeCalendar, calendarDialogId } =
+    useDatePicker();
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  return (
+    <>
+      <Box width="fit-content" onClick={openCalendar}>
+        <DatePickerInput ref={inputRef} />
+      </Box>
+      <PopoverContainer
+        alignment="bottom-left"
+        allowPageInteraction
+        focusOnProps={{ autoFocus: false, focusLock: false }}
+        invertAxis="x"
+        isOpen={isCalendarOpen}
+        offset={10}
+        targetRef={inputRef}
+        onRequestClose={closeCalendar}
+      >
+        <div aria-label="Choose date" id={calendarDialogId} role="dialog">
+          <DatePickerCalendar dialogId={calendarDialogId} />
+        </div>
+      </PopoverContainer>
+    </>
+  );
+}

package/src/lib/UX Writing/Component guidelines/Confirmation dialogs.mdx

@@ -1,11 +1,11 @@
 import { Meta } from '@storybook/blocks';
 
-import { AboutHeader, ImageWrapper, LinkTo } from '~styleguide/blocks';
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
 
 export const parameters = {
   title: 'Confirmation dialogs',
   subtitle:
-    'Use the same verb from the triggering button, heading, to action confirmation button; clearly communicate the consequences; and keep the copy decision-focused.',
+    'Simplify the language, prioritize the message, and make sure the implication of what learners are saying "Yes" (or "No") to is crystal clear.',
   status: 'static',
   design: {
     type: 'figma',
@@ -17,57 +17,39 @@ export const parameters = {
 
 <AboutHeader {...parameters} />
 
-Confirmation dialogs use the <LinkTo id="Molecules/Modals/Dialog">Dialog component in Gamut</LinkTo> to create intentional friction to verify that a learner wants to take a high-impact action, such as:
+Confirmation dialog boxes are used to verify that a learner wants to take a specific action. They are generally used for actions that are irreversible, may result in critical consequences or loss of data, have other severe consequences, or happen infrequently.
 
-- Irreversible actions (e.g., submitting payment)
-- Loss of data, time, or work (e.g., deleting a course)
-- Unexpected consequences (e.g., losing learning history on an existing prototype when when generating a new prototype)
-
-Adding friction for these purposes helps improve trust and avoid unintentional actions by making sure learners clearly understand the consequences before continuing. It also lets us offer alternatives or undo options when needed.
+They use the <LinkTo id="Molecules/Modals/Dialog">Dialog component in Gamut</LinkTo> and, for actions with serious or irreversible consequences, the `Danger` variant should be used.
 
 ## Best practices
 
-### Heading
-
-- **Ask or inform about one main action**, mirroring the button that triggered the confirmation dialog.
-- **Frame your headline as a binary question**, when possible, with 2 unambiguous answers.
-- **Avoid generic “Are you sure?” headings and body text.** This phrasing takes up space, increases cognitive load, and may undermine users' confidence or be interpreted as patronizing.
-
-### Body (optional)
-
-- **Add essential information about the contextual consequences.** State what will happen, what will be lost/changed, and any critical conditions.
-- **Avoid redundancy.** If the heading is already self-explanatory, the body is not needed.
-- **Keep to 1–2 lines, unless more is required to get all the information across.**
-
-### Buttons (CTA1 and CTA2)
+### Headline
 
-- **Avoid using “Yes” or “No,”** as they can be misinterpreted in global English and internationalization contexts.
-- **CTA1 matches the verb from the heading** to confirm the action.
-- **CTA2 clarifies the alternative or undo** path.
-  - Whenever possible, be specific about the alternative. However, when space is limited, 'Cancel' can be used.
+- **Ask or inform about one main action**, clearly and simply.
+- **Frame your headline as a binary question**, when possible, with 2 unambiguous answers (i.e. Yes/No, Stay/Leave).
+- **Be specific.** Instead of "Are you sure?" focus on what you want to ensure they're sure about (i.e. "Reset your progress?" or "Delete the file?").
 
-### Examples — putting it all together
+### Explanation
 
-<ImageWrapper
-  src="./ux writing/delete_this_course.png"
-  alt="Delete this course confirmation dialog"
-/>
+- **Share only relevant information** that may help the learner make their decision.
+- **Avoid redundancy.** If you've already set the stage in your headline, there's no need to re-ask the same question in your explanation. If the explanation doesn't add anything new, leave it out (i.e. "Permanently delete this item? Yes/No").
+- **Avoid filler.** Questions like "Are you sure you want to \_\_\_?" take up space, increase cognitive load, and may undermine users' confidence or be interpreted as patronizing.
+- **Keep to 1-2 lines**, unless more is required to get all the information across.
 
-<ImageWrapper
-  src="./ux writing/delete_study_plan.png"
-  alt="Delete study plan confirmation dialog"
-/>
+### Button copy
 
-<ImageWrapper
-  src="./ux writing/clear_chat.png"
-  alt="Clear chat confirmation dialog"
-/>
+- **Options should be clear and distinct.** Each option should be distinctly different and there should be no opportunity for learners to mix them up (i.e. "Delete" and "Cancel" are ambiguous choices whereas "Yes, remove" and "Cancel" clear up the confusion.
+- **Add context to reaffirm the action.** Instead of "Yes," use "Yes, reset progress."
+- **Match the verb in your headline.** If you use "Save" in your headline, use "Save" in your button copy, rather than keep. Consistency helps keep the message clear. All of this should also match whatever the learner clicked on that triggered the confirmation dialog.
 
 ## Checklist
 
-- Is the action irreversible, destructive, or has unexpected consequences? If not, consider using a different pattern.
-- Is the same verb used from the action triggering the confirmation dialog, to the heading, to CTA1?
-- Did you avoid filler language such as “Are you sure you want to...?”
-- Does the body front-load the critical consequence in 1–3 lines?
-- Are the buttons mutually exclusive (and avoid using “Yes/No”)?
-- Is there a safer alternative or undo to mention? (If available, offer the option as CTA2.)
+- Is the language consistent from the wording on the button that opened the confirmation box, to the headline,
+- Does the headline make the action clear?
+- Is the headline framed as a question, if possible?
+- Does the explanation provide relevant details and consequences of the action?
+- Is the explanation 1-2 lines long?
+- Are the words on the buttons clear and distinct?
+- Do the buttons include context to reaffirm the action?
+- Is your copy at a reading level of grade 7 or below? Test with [Hemingway App](https://hemingwayapp.com).
+- Have you asked someone unrelated to the project to read the message and did they understand it?