@12-apps/ui 6.80.0 → 6.82.0

package/src/components/form/Calendar/CalendarPickerGrid.tsx

@@ -0,0 +1,139 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import Box from '@mui/material/Box/index.js';
+import type { FC } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
+
+import { rem, sxRem } from '../../../tokens/relative';
+
+import { moveInGrid } from './Calendar.views';
+
+/** A pick button's smallest edge: a touch target at any width (44 design px). */
+const TARGET_SIZE = sxRem(44);
+
+export interface PickerOption {
+  value: number;
+  label: string;
+  /** The accessible name, when the visible label is an abbreviation ("mar"). */
+  ariaLabel?: string;
+  disabled: boolean;
+  /** The month or year the calendar is showing. */
+  current: boolean;
+}
+
+const inkFor = ({ current, disabled }: PickerOption): string => {
+  if (current) return 'primary.contrastText';
+  return disabled ? 'text.disabled' : 'text.primary';
+};
+
+const optionSx = (option: PickerOption): SxProps<Theme> => ({
+  minHeight: TARGET_SIZE,
+  minWidth: 0,
+  boxSizing: 'border-box',
+  padding: 0,
+  font: 'inherit',
+  typography: 'body1',
+  border: 1,
+  borderColor: option.current ? 'primary.main' : 'divider',
+  borderRadius: 1,
+  backgroundColor: option.current ? 'primary.main' : 'transparent',
+  color: inkFor(option),
+  cursor: option.disabled ? 'not-allowed' : 'pointer',
+  '&:hover': { backgroundColor: option.current || option.disabled ? undefined : 'action.hover' },
+  '&:focus-visible': {
+    outline: (theme: Theme) => `${rem(theme, 2)} solid`,
+    outlineColor: 'primary.main',
+    outlineOffset: sxRem(1),
+  },
+});
+
+// The grid fills the box the day grid leaves (see CalendarSelectorsMonth), so
+// opening it never resizes the calendar: a short grid's rows stretch to fill
+// it, a long one scrolls inside it.
+const gridSx = (columns: number, scrollable: boolean): SxProps<Theme> => ({
+  display: 'grid',
+  gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+  gap: 1,
+  boxSizing: 'border-box',
+  height: '100%',
+  // Room for the focus ring of the edge buttons inside the box.
+  p: 0.5,
+  ...(scrollable ? { alignContent: 'start', overflowY: 'auto' } : { gridAutoRows: '1fr' }),
+});
+
+export interface CalendarPickerGridProps {
+  id: string;
+  ariaLabel: string;
+  columns: number;
+  options: PickerOption[];
+  testId: string;
+  scrollable?: boolean;
+  onPick: (value: number) => void;
+  onDismiss: () => void;
+}
+
+/**
+ * The month or year grid that stands in for the days. One tab stop (roving
+ * `tabIndex`); arrows, Home and End move it, Enter/Space pick, Escape goes back
+ * to the days unchanged. Out-of-bounds options stay focusable and say
+ * `aria-disabled`, so the arrows never skip a hole a reader cannot explain.
+ */
+export const CalendarPickerGrid: FC<CalendarPickerGridProps> = ({
+  id,
+  ariaLabel,
+  columns,
+  options,
+  testId,
+  scrollable = false,
+  onPick,
+  onDismiss,
+}) => {
+  const [active, setActive] = useState(() => Math.max(options.findIndex((option) => option.current), 0));
+  const buttons = useRef<Array<HTMLButtonElement | null>>([]);
+
+  // Also runs on mount: opening the grid puts focus on the shown month/year,
+  // which scrolls a long year list to it.
+  useEffect(() => {
+    buttons.current[active]?.focus();
+  }, [active]);
+
+  const handleKeyDown = (event: React.KeyboardEvent) => {
+    // The calendar's own day keys must not move a day nobody can see.
+    event.stopPropagation();
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      onDismiss();
+      return;
+    }
+    const next = moveInGrid(event.key, active, columns, options.length);
+    if (next === null) return;
+    event.preventDefault();
+    setActive(next);
+  };
+
+  return (
+    <Box id={id} role="group" aria-label={ariaLabel} data-testid={testId} onKeyDown={handleKeyDown} sx={gridSx(columns, scrollable)}>
+      {options.map((option, index) => (
+        <Box
+          key={option.value}
+          component="button"
+          type="button"
+          ref={(node: HTMLButtonElement | null) => {
+            buttons.current[index] = node;
+          }}
+          tabIndex={index === active ? 0 : -1}
+          aria-current={option.current ? 'true' : undefined}
+          aria-disabled={option.disabled || undefined}
+          aria-label={option.ariaLabel}
+          data-testid={`${testId}-${option.value}`}
+          onFocus={() => setActive(index)}
+          onClick={() => {
+            if (!option.disabled) onPick(option.value);
+          }}
+          sx={optionSx(option)}
+        >
+          {option.label}
+        </Box>
+      ))}
+    </Box>
+  );
+};

package/src/components/form/Calendar/CalendarSelectorsCaption.tsx

@@ -0,0 +1,163 @@
+import ArrowDropDown from '@mui/icons-material/ArrowDropDown';
+import ChevronLeft from '@mui/icons-material/ChevronLeft';
+import ChevronRight from '@mui/icons-material/ChevronRight';
+import Box from '@mui/material/Box/index.js';
+import Button from '@mui/material/Button/index.js';
+import IconButton from '@mui/material/IconButton/index.js';
+import type { FC } from 'react';
+import React from 'react';
+
+import type { CalendarLabels } from '../../../copy/labels';
+import { sxRem } from '../../../tokens/relative';
+
+import type { CalendarView } from './Calendar.views';
+
+/** Every control in the caption is a touch target at any width (44 design px). */
+const TARGET_SIZE = sxRem(44);
+
+/**
+ * The shown month over every month name, hidden: the button keeps the width of
+ * the longest, so stepping from Agosto to Setembro moves nothing.
+ */
+const MonthText: FC<{ text: string; names: string[] }> = ({ text, names }) => (
+  <Box component="span" sx={{ display: 'inline-grid', justifyItems: 'start' }}>
+    {names.map((name) => (
+      <Box key={name} component="span" aria-hidden sx={{ gridArea: '1 / 1', visibility: 'hidden' }}>
+        {name}
+      </Box>
+    ))}
+    <Box component="span" data-testid="calendar-month-select-text" sx={{ gridArea: '1 / 1' }}>
+      {text}
+    </Box>
+  </Box>
+);
+
+const SelectorButton: FC<{
+  testId: string;
+  text: React.ReactNode;
+  ariaLabel: string;
+  expanded: boolean;
+  controls: string;
+  onClick: () => void;
+}> = ({ testId, text, ariaLabel, expanded, controls, onClick }) => (
+  <Button
+    type="button"
+    color="inherit"
+    data-testid={testId}
+    aria-label={ariaLabel}
+    aria-expanded={expanded}
+    aria-controls={expanded ? controls : undefined}
+    endIcon={<ArrowDropDown />}
+    onClick={onClick}
+    sx={{
+      minHeight: TARGET_SIZE,
+      px: 0.5,
+      whiteSpace: 'nowrap',
+      textTransform: 'none',
+      typography: 'subtitle1',
+      fontWeight: 'bold',
+      border: 1,
+      borderColor: 'divider',
+      backgroundColor: expanded ? 'action.selected' : 'transparent',
+    }}
+  >
+    {text}
+  </Button>
+);
+
+const ARROW_SX = { width: TARGET_SIZE, height: TARGET_SIZE } as const;
+
+export interface CalendarSelectorsCaptionProps {
+  monthText: string;
+  /** Every month's name in the locale, which sizes the month button. */
+  monthNames: string[];
+  year: number;
+  view: CalendarView;
+  labels: CalendarLabels;
+  /** The id of the pick grid each button opens. */
+  monthsId: string;
+  yearsId: string;
+  canGoPrevious: boolean;
+  canGoNext: boolean;
+  onToggle: (view: Exclude<CalendarView, 'days'>) => void;
+  /** Escape on a caption control closes an open grid; with none open it is the host's. */
+  onEscape: () => void;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+}
+
+/**
+ * `<Month> ▾` and `<Year> ▾`, then the month arrows. Its keys are its own: the
+ * container's day keys would otherwise turn Enter on a button into a day pick.
+ * Escape is the exception while no grid is open, so the sheet or popover that
+ * holds the calendar still closes on it.
+ */
+export const CalendarSelectorsCaption: FC<CalendarSelectorsCaptionProps> = ({
+  monthText,
+  monthNames,
+  year,
+  view,
+  labels,
+  monthsId,
+  yearsId,
+  canGoPrevious,
+  canGoNext,
+  onToggle,
+  onEscape,
+  onPreviousMonth,
+  onNextMonth,
+}) => (
+  <Box
+    data-testid="calendar-header"
+    onKeyDown={(event) => {
+      if (event.key === 'Escape' && view === 'days') return;
+      event.stopPropagation();
+      if (event.key === 'Escape') onEscape();
+    }}
+    // Two groups that wrap rather than squeeze: in a 320 sheet the arrows take
+    // a second line, and no button shrinks below a touch target. The month
+    // button is as wide as the longest month name, so whether they wrap depends
+    // on the width only, never on the month shown.
+    sx={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 1, mb: 2 }}
+  >
+    <Box sx={{ display: 'flex', gap: 0.5 }}>
+      <SelectorButton
+        testId="calendar-month-select"
+        text={<MonthText text={monthText} names={monthNames} />}
+        ariaLabel={labels.chooseMonth(monthText)}
+        expanded={view === 'months'}
+        controls={monthsId}
+        onClick={() => onToggle('months')}
+      />
+      <SelectorButton
+        testId="calendar-year-select"
+        text={String(year)}
+        ariaLabel={labels.chooseYear(year)}
+        expanded={view === 'years'}
+        controls={yearsId}
+        onClick={() => onToggle('years')}
+      />
+    </Box>
+
+    <Box sx={{ display: 'flex', ml: 'auto' }}>
+      <IconButton
+        aria-label={labels.previousMonth}
+        disabled={!canGoPrevious}
+        onClick={onPreviousMonth}
+        data-testid="calendar-prev-month"
+        sx={ARROW_SX}
+      >
+        <ChevronLeft />
+      </IconButton>
+      <IconButton
+        aria-label={labels.nextMonth}
+        disabled={!canGoNext}
+        onClick={onNextMonth}
+        data-testid="calendar-next-month"
+        sx={ARROW_SX}
+      >
+        <ChevronRight />
+      </IconButton>
+    </Box>
+  </Box>
+);

package/src/components/form/Calendar/CalendarSelectorsMonth.tsx

@@ -0,0 +1,137 @@
+import Box from '@mui/material/Box/index.js';
+import type { FC } from 'react';
+import React, { useId } from 'react';
+
+import type { CalendarLabels } from '../../../copy/labels';
+
+import { getMonthLabel } from './Calendar.dates';
+import type { CalendarPicker } from './Calendar.picker';
+import type { MonthMatrix } from './Calendar.types';
+import type { DateBounds } from './Calendar.views';
+import { MONTH_INDEXES, canShiftMonth, isMonthOutOfBounds, isYearOutOfBounds, yearOptions } from './Calendar.views';
+import type { DayCellContext } from './CalendarDayCell';
+import { MONTH_SX, MonthDays } from './CalendarMonth';
+import type { PickerOption } from './CalendarPickerGrid';
+import { CalendarPickerGrid } from './CalendarPickerGrid';
+import { CalendarSelectorsCaption } from './CalendarSelectorsCaption';
+
+/** The days and the open grid share one cell, so opening a grid never resizes the calendar. */
+const BODY_SX = { display: 'grid' } as const;
+
+/** Adds no height of its own; a long year list scrolls inside the days' height. */
+const PICKER_SLOT_SX = {
+  gridArea: '1 / 1',
+  height: 0,
+  minHeight: '100%',
+} as const;
+
+const YEAR_COLUMNS = 4;
+const MONTH_COLUMNS = 3;
+
+export interface CalendarSelectorsMonthProps {
+  matrix: MonthMatrix;
+  locale: string;
+  weekdayNames: string[];
+  dayContext: DayCellContext;
+  bounds: DateBounds;
+  labels: CalendarLabels;
+  picker: CalendarPicker;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+}
+
+const monthOptions = ({ year, month }: MonthMatrix, locale: string, bounds: DateBounds): PickerOption[] =>
+  MONTH_INDEXES.map((index) => ({
+    value: index,
+    label: getMonthLabel(index, locale, 'short'),
+    ariaLabel: getMonthLabel(index, locale, 'long'),
+    disabled: isMonthOutOfBounds(year, index, bounds),
+    current: index === month,
+  }));
+
+// The list is cut at the bounds' years, so only a shown year outside them is
+// disabled.
+const yearPickerOptions = ({ year }: MonthMatrix, bounds: DateBounds): PickerOption[] =>
+  yearOptions(bounds, year).map((option) => ({
+    value: option,
+    label: String(option),
+    disabled: isYearOutOfBounds(option, bounds),
+    current: option === year,
+  }));
+
+/**
+ * The one month of `captionLayout="selectors"`: the month/year caption over the
+ * days, or over the month or year grid that stands in for them.
+ */
+export const CalendarSelectorsMonth: FC<CalendarSelectorsMonthProps> = ({
+  matrix,
+  locale,
+  weekdayNames,
+  dayContext,
+  bounds,
+  labels,
+  picker,
+  onPreviousMonth,
+  onNextMonth,
+}) => {
+  const idPrefix = useId();
+  const monthsId = `${idPrefix}-months`;
+  const yearsId = `${idPrefix}-years`;
+  const shown = new Date(matrix.year, matrix.month, 1);
+
+  const picking = picker.view !== 'days';
+
+  return (
+    <Box sx={MONTH_SX} data-testid="calendar-month-0">
+      <CalendarSelectorsCaption
+        monthText={getMonthLabel(matrix.month, locale, 'long')}
+        monthNames={MONTH_INDEXES.map((index) => getMonthLabel(index, locale, 'long'))}
+        year={matrix.year}
+        view={picker.view}
+        labels={labels}
+        monthsId={monthsId}
+        yearsId={yearsId}
+        canGoPrevious={canShiftMonth(shown, -1, bounds)}
+        canGoNext={canShiftMonth(shown, 1, bounds)}
+        onToggle={picker.toggle}
+        onEscape={picker.dismiss}
+        onPreviousMonth={onPreviousMonth}
+        onNextMonth={onNextMonth}
+      />
+
+      <Box sx={BODY_SX}>
+        {/* The days keep their place while a grid is open, so the calendar keeps their size at every density. */}
+        <Box sx={{ gridArea: '1 / 1', visibility: picking ? 'hidden' : 'visible' }} data-testid="calendar-days">
+          <MonthDays matrix={matrix} monthIndex={0} weekdayNames={weekdayNames} dayContext={dayContext} />
+        </Box>
+        {picking && (
+          <Box sx={PICKER_SLOT_SX}>
+            {picker.view === 'months' && (
+              <CalendarPickerGrid
+                id={monthsId}
+                ariaLabel={labels.months}
+                columns={MONTH_COLUMNS}
+                options={monthOptions(matrix, locale, bounds)}
+                testId="calendar-months"
+                onPick={picker.pickMonth}
+                onDismiss={picker.dismiss}
+              />
+            )}
+            {picker.view === 'years' && (
+              <CalendarPickerGrid
+                id={yearsId}
+                ariaLabel={labels.years}
+                columns={YEAR_COLUMNS}
+                options={yearPickerOptions(matrix, bounds)}
+                testId="calendar-years"
+                scrollable
+                onPick={picker.pickYear}
+                onDismiss={picker.dismiss}
+              />
+            )}
+          </Box>
+        )}
+      </Box>
+    </Box>
+  );
+};

package/src/components/form/Calendar/index.ts

@@ -1,5 +1,6 @@
 export { Calendar,Calendar as default } from './Calendar';
 export type {
+  CalendarCaptionLayout,
   CalendarInternalState,
   CalendarProps,
   DateRange,

package/src/components/form/Checkbox/Checkbox.md

@@ -51,6 +51,7 @@ import { Checkbox } from '@/components/form/Checkbox';
 | error | `boolean` | `false` | Error state flag |
 | helperText | `string` | - | Helper or error text displayed below |
 | loading | `boolean` | `false` | Shows loading spinner and disables checkbox |
+| loadingLabel | `string` | `loading` | React Native only: the busy spinner's accessible name (`UI_LABELS[locale].common.loading`) |
 | ripple | `boolean` | `true` | Enable/disable ripple effect on click |
 | glow | `boolean` | `false` | Enable glow animation |
 | pulse | `boolean` | `false` | Enable pulse animation |

package/src/components/form/Input/Input.md

@@ -34,6 +34,7 @@ The Input component provides a flexible text input field with comprehensive vali
 - `error`: Error state flag
 - `helperText`: Helper or error text displayed below input
 - `loading`: Shows loading spinner and disables input
+- `loadingLabel`: React Native only — the busy spinner's accessible name (`string`, default `loading`; `UI_LABELS[locale].common.loading`)
 
 ### Visual Props
 - `fullWidth`: Makes input take full container width (default: true)

package/src/components/form/RichTextEditor/RichTextEditor.md

@@ -79,7 +79,8 @@ function App() {
 |------|------|---------|-------------|
 | `value` | `string` | `''` | The current value of the rich text editor content |
 | `onChange` | `(value: string) => void` | - | Callback when the content changes |
-| `placeholder` | `string` | `'Start typing...'` | Placeholder text when empty |
+| `placeholder` | `string` | `'Start typing...'` | Placeholder text when empty; defaults to `labels.placeholder` |
+| `labels` | `Partial<RichTextEditorLabels>` | English pack | The toolbar's tooltips (`bold`, `italic`, `underline`, `strikethrough`, `numberedList`, `bulletedList`, `insertLink`, `insertImage`, `codeBlock`, `quote`), the link and image prompts (`linkPrompt`, `imagePrompt`), the new list item's text (`listItem`), the default `placeholder` and the default `ariaLabel`. Any key left out reads in English (`Bold`, `Enter URL:`, `Start typing...`, `Rich text editor`, …); a pt-BR host passes `UI_LABELS['pt-BR'].richTextEditor` |
 | `disabled` | `boolean` | `false` | Whether the editor is disabled |
 | `readOnly` | `boolean` | `false` | Whether the editor is read-only |
 | `toolbar` | `ToolbarConfig` | Default config | Configuration for toolbar buttons and features |
@@ -89,7 +90,7 @@ function App() {
 | `onBlur` | `() => void` | - | Callback when editor loses focus |
 | `className` | `string` | - | Additional CSS classes |
 | `data-testid` | `string` | - | Test ID for testing purposes |
-| `aria-label` | `string` | `'Rich text editor'` | ARIA label for accessibility |
+| `aria-label` | `string` | `'Rich text editor'` | ARIA label for accessibility; defaults to `labels.ariaLabel` |
 | `aria-describedby` | `string` | - | ARIA described by for accessibility |
 
 ## ToolbarConfig

package/src/components/form/Switch/Switch.md

@@ -86,6 +86,7 @@ import { Switch } from '@procurement/ui';
 | `onChange`      | `(event, checked) => void`                                                    | -           | Change event handler                             |
 | `animated`      | `boolean`                                                                     | `true`      | Enable/disable animations                        |
 | `loading`       | `boolean`                                                                     | `false`     | Shows loading spinner and disables switch        |
+| `loadingLabel`  | `string`                                                                      | `loading`   | React Native only: the busy spinner's accessible name (`UI_LABELS[locale].common.loading`) |
 | `ripple`        | `boolean`                                                                     | `false`     | Enable ripple effect on interaction              |
 | `pulse`         | `boolean`                                                                     | `false`     | Enable pulse animation on thumb                  |
 | `disabled`      | `boolean`                                                                     | `false`     | Disables switch interaction                      |

package/src/components/layout/ContentToolbar/ContentToolbar.md

@@ -36,6 +36,18 @@ pages and projects.
 | `MultiSelectDropdown` | Checkbox multi-select with counts, an optional "Options" section, and a Clear action (e.g. "Content Type"). |
 | `FilterTrigger` | Funnel toggle button with an active-filters indicator dot. |
 
+### Label props
+
+Optional; each omitted one reads in English. A host passes
+`UI_LABELS[locale].contentToolbar` from `@12-apps/ui/locales`.
+
+| Prop | On | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `gridViewLabel` | `ViewSelector` | `string` | `"Grid View"` | The grid option's name, in the menu and on the trigger while it is active (`contentToolbar.gridView`) |
+| `listViewLabel` | `ViewSelector` | `string` | `"List View"` | The list option's name (`contentToolbar.listView`) |
+| `openFiltersLabel` | `FilterTrigger` | `string` | `"Open filters"` | The button's accessible name while the panel is closed (`contentToolbar.openFilters`) |
+| `closeFiltersLabel` | `FilterTrigger` | `string` | `"Close filters"` | The button's accessible name while the panel is open (`contentToolbar.closeFilters`) |
+
 ## Usage
 
 ```tsx

package/src/components/layout/Dashboard/Dashboard.md

@@ -63,6 +63,9 @@ import { Dashboard } from '@12-apps/ui/layout/Dashboard';
 | `Dashboard.MoreFilters` | (in filters) | Expandable advanced panel for ranges/dates. |
 | `Dashboard.Body` | body | Main content area (the table/grid). |
 
+`Dashboard.Breadcrumb` takes `ariaLabel?: string`, the trail's landmark name
+(default `"breadcrumb"`); a host passes `UI_LABELS[locale].dashboard.breadcrumb`.
+
 ## State
 
 `Dashboard` owns only **UI** state (which regions are open) through

package/src/components/navigation/NavigationMenu/NavigationMenu.md

@@ -26,6 +26,8 @@ A flexible and feature-rich navigation menu component that supports horizontal,
 | collapsible       | `boolean`                                 | false      | Whether the vertical menu can be collapsed              |
 | collapsed         | `boolean`                                 | undefined  | Controlled collapsed state                              |
 | onCollapseChange  | `(collapsed: boolean) => void`           | undefined  | Callback when collapse state changes                    |
+| collapseLabel     | `string`                                  | 'Collapse' | The collapse control's text (vertical, `collapsible` only); `UI_LABELS[locale].navigationMenu.collapse` |
+| expandLabel       | `string`                                  | 'Expand'   | The collapse control's accessible name while collapsed to its icon (vertical, `collapsible` only); `UI_LABELS[locale].navigationMenu.expand` |
 | logo              | `ReactNode`                               | undefined  | Custom logo/brand element                               |
 | endContent        | `ReactNode`                               | undefined  | Additional content to render at the end                 |
 | maxWidth          | `number \| string`                       | undefined  | Maximum width for mega menu                             |

package/src/components/typography/Code/Code.md

@@ -33,6 +33,16 @@ The Code component is a versatile typography element designed for displaying cod
 - **Default**: `false`
 - **Description**: Enables copy-to-clipboard functionality with visual feedback (block/highlight variants only)
 
+### copyLabel
+- **Type**: `string`
+- **Default**: `'Copy code'`
+- **Description**: The copy button's tooltip and accessible name (`UI_LABELS[locale].code.copy`)
+
+### copiedLabel
+- **Type**: `string`
+- **Default**: `'Copied!'`
+- **Description**: The same button right after a copy (`UI_LABELS[locale].code.copied`)
+
 ### lineNumbers
 - **Type**: `boolean`
 - **Default**: `false`

package/src/components/utility/InfiniteScroll/InfiniteScroll.md

@@ -60,6 +60,7 @@ function MyComponent() {
 | `loader` | `ReactNode` | Default spinner | Custom loading indicator |
 | `endMessage` | `ReactNode` | Default message | Message when no more items |
 | `error` | `Error \| null` | - | Error object if load failed |
+| `errorText` | `string` | `"An error occurred while loading more items"` | The error line when `error` carries no message of its own; a pt-BR host passes `UI_LABELS['pt-BR'].infiniteScroll.loadFailed` |
 | `errorComponent` | `ReactNode` | Default error UI | Custom error component |
 | `onError` | `(error: Error) => void` | - | Error callback |
 | `className` | `string` | - | CSS class name |

package/src/components/utility/WorkflowStep/WorkflowStep.md

@@ -35,6 +35,7 @@ The WorkflowStep component is an advanced workflow visualization component that
 | `errorIcon` | `React.ReactNode` | - | Custom icon for error steps |
 | `onStepClick` | `(stepIndex: number) => void` | - | Callback when a step is clicked |
 | `disabled` | `boolean` | `false` | Disable all interactions |
+| `labels` | `Partial<WorkflowStepLabels>` | English pack | The indicators' accessible names, `step(position, title)` (`` `Step ${position}: ${title}` ``), and the progressbar's value text, `progress(position, total)` (`` `Step ${position} of ${total}` ``). Any key left out keeps its English wording; a host passes `UI_LABELS[locale].workflowStep` |
 | `className` | `string` | - | Additional CSS classes |
 | `style` | `React.CSSProperties` | - | Inline styles |
 

package/src/copy/labels.ts

@@ -214,6 +214,24 @@ export interface DateRangePickerLabels {
   calendar: string;
 }
 
+/**
+ * `Calendar`'s month/year caption (`captionLayout="selectors"`): the two
+ * selector buttons, the month arrows and the two pick grids. The month and
+ * year themselves come from `Intl` in the calendar's `locale`.
+ */
+export interface CalendarLabels {
+  /** The month button's accessible name, from the month it shows ("March"). */
+  chooseMonth(month: string): string;
+  /** The year button's accessible name, from the year it shows. */
+  chooseYear(year: number): string;
+  previousMonth: string;
+  nextMonth: string;
+  /** The month grid's accessible name. */
+  months: string;
+  /** The year grid's accessible name. */
+  years: string;
+}
+
 /** Every family above, keyed by the component that renders it. */
 export interface UiLabels {
   common: CommonLabels;
@@ -246,4 +264,5 @@ export interface UiLabels {
   infiniteScroll: InfiniteScrollLabels;
   socialLogin: SocialLoginLabels;
   dateRangePicker: DateRangePickerLabels;
+  calendar: CalendarLabels;
 }

package/src/en-US.labels.ts

@@ -144,4 +144,12 @@ export const EN_US_UI_LABELS: UiLabels = {
   dateRangePicker: {
     calendar: "Calendar",
   },
+  calendar: {
+    chooseMonth: (month) => `${month}, choose month`,
+    chooseYear: (year) => `${year}, choose year`,
+    previousMonth: "Previous month",
+    nextMonth: "Next month",
+    months: "Months",
+    years: "Years",
+  },
 };

package/src/pt-BR.labels.ts

@@ -143,4 +143,12 @@ export const PT_BR_UI_LABELS: UiLabels = {
   dateRangePicker: {
     calendar: "Calendário",
   },
+  calendar: {
+    chooseMonth: (month) => `${month}, escolher mês`,
+    chooseYear: (year) => `${year}, escolher ano`,
+    previousMonth: "Mês anterior",
+    nextMonth: "Próximo mês",
+    months: "Meses",
+    years: "Anos",
+  },
 };

package/dist/chunk-ISW5K72V.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/form/Calendar/Calendar.hooks.ts"],"sourcesContent":["import type React from 'react';\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\n\nimport { addMonths, generateMonthMatrix, getWeekdayNames, normalizeDate } from './Calendar.dates';\nimport { ACTIVATION_KEYS, navigateFocus } from './Calendar.keyboard';\nimport { isDateDisabledBy, nextRangeStep } from './Calendar.selection';\nimport type { MonthMatrix, ResolvedCalendarProps } from './Calendar.types';\n\nconst startOfMonth = (date: Date): Date => new Date(date.getFullYear(), date.getMonth(), 1);\n\n// Which day the calendar opens on: whatever is already chosen, else today.\nconst initialFocus = (props: ResolvedCalendarProps, today: Date): Date => {\n  if (props.selectionMode === 'single' && props.value) return normalizeDate(props.value);\n  if (props.selectionMode === 'range' && props.range.start) return normalizeDate(props.range.start);\n  return today;\n};\n\nconst useCalendarState = (props: ResolvedCalendarProps, today: Date) => {\n  const [focusedDate, setFocusedDate] = useState<Date>(() => initialFocus(props, today));\n  const [hoveredDate, setHoveredDate] = useState<Date | null>(null);\n  const [currentMonth, setCurrentMonth] = useState<Date>(() => startOfMonth(focusedDate));\n\n  return {\n    focusedDate,\n    setFocusedDate,\n    hoveredDate,\n    setHoveredDate,\n    currentMonth,\n    setCurrentMonth,\n  };\n};\n\nconst useAutoFocusGrid = (autoFocus: boolean) => {\n  const gridRef = useRef<HTMLDivElement>(null);\n\n  useEffect(() => {\n    if (autoFocus && gridRef.current) gridRef.current.focus();\n  }, [autoFocus]);\n\n  return gridRef;\n};\n\nconst useVisibleMonths = ({\n  currentMonth,\n  monthsToShow,\n  firstDayOfWeek,\n}: {\n  currentMonth: Date;\n  monthsToShow: number;\n  firstDayOfWeek: number;\n}): MonthMatrix[] =>\n  useMemo(() => {\n    const matrices: MonthMatrix[] = [];\n    let cursor = currentMonth;\n\n    for (let i = 0; i < monthsToShow; i++) {\n      matrices.push(generateMonthMatrix(cursor.getMonth(), cursor.getFullYear(), firstDayOfWeek));\n      cursor = addMonths(cursor, 1);\n    }\n\n    return matrices;\n  }, [currentMonth, monthsToShow, firstDayOfWeek]);\n\n// A click either sets a single date or advances the range by one step; the range\n// rules themselves live in nextRangeStep.\nconst useDateClick = ({\n  props,\n  isDisabled,\n  setFocusedDate,\n}: {\n  props: ResolvedCalendarProps;\n  isDisabled: (date: Date) => boolean;\n  setFocusedDate: (date: Date) => void;\n}) => {\n  const {\n    selectionMode,\n    range,\n    onChange,\n    onRangeChange,\n    onIntermediateRangeChange,\n    allowSameDayRange,\n    minRangeLength,\n    maxRangeLength,\n  } = props;\n\n  return useCallback(\n    (date: Date) => {\n      if (isDisabled(date)) return;\n\n      const candidate = normalizeDate(date);\n      setFocusedDate(candidate);\n\n      if (selectionMode === 'single') {\n        onChange?.(candidate);\n        return;\n      }\n\n      const step = nextRangeStep({\n        start: range.start,\n        end: range.end,\n        candidate,\n        allowSameDayRange,\n        minRangeLength,\n        maxRangeLength,\n      });\n\n      if (step.kind === 'rejected') return;\n\n      if (step.kind === 'complete') onRangeChange?.(step.range);\n      onIntermediateRangeChange?.(step.range);\n    },\n    [\n      selectionMode,\n      range,\n      onChange,\n      onRangeChange,\n      onIntermediateRangeChange,\n      isDisabled,\n      allowSameDayRange,\n      minRangeLength,\n      maxRangeLength,\n      setFocusedDate,\n    ],\n  );\n};\n\n// Hovering only means something while a range is half-chosen.\nconst useHoverHandlers = ({\n  selectionMode,\n  range,\n  isDisabled,\n  setHoveredDate,\n}: {\n  selectionMode: ResolvedCalendarProps['selectionMode'];\n  range: ResolvedCalendarProps['range'];\n  isDisabled: (date: Date) => boolean;\n  setHoveredDate: (date: Date | null) => void;\n}) => {\n  const handleDateMouseEnter = useCallback(\n    (date: Date) => {\n      if (selectionMode === 'range' && range.start && !range.end && !isDisabled(date)) {\n        setHoveredDate(normalizeDate(date));\n      }\n    },\n    [selectionMode, range, isDisabled, setHoveredDate],\n  );\n\n  const handleDateMouseLeave = useCallback(() => setHoveredDate(null), [setHoveredDate]);\n\n  return { handleDateMouseEnter, handleDateMouseLeave };\n};\n\nconst useKeyboardHandler = ({\n  focusedDate,\n  firstDayOfWeek,\n  currentMonth,\n  handleDateClick,\n  setFocusedDate,\n  setCurrentMonth,\n  setHoveredDate,\n}: {\n  focusedDate: Date;\n  firstDayOfWeek: number;\n  currentMonth: Date;\n  handleDateClick: (date: Date) => void;\n  setFocusedDate: (date: Date) => void;\n  setCurrentMonth: (date: Date) => void;\n  setHoveredDate: (date: Date | null) => void;\n}) =>\n  useCallback(\n    (event: React.KeyboardEvent) => {\n      const { key } = event;\n      const moved = navigateFocus(key, focusedDate, { firstDayOfWeek, shiftKey: event.shiftKey });\n\n      if (moved) {\n        event.preventDefault();\n        setFocusedDate(normalizeDate(moved));\n\n        // Follow focus into a month that is not on screen.\n        const month = startOfMonth(moved);\n        if (month.getTime() !== currentMonth.getTime()) setCurrentMonth(month);\n        return;\n      }\n\n      if (ACTIVATION_KEYS.includes(key)) {\n        event.preventDefault();\n        handleDateClick(focusedDate);\n        return;\n      }\n\n      if (key === 'Escape') {\n        event.preventDefault();\n        setHoveredDate(null);\n      }\n    },\n    [\n      focusedDate,\n      firstDayOfWeek,\n      currentMonth,\n      handleDateClick,\n      setFocusedDate,\n      setCurrentMonth,\n      setHoveredDate,\n    ],\n  );\n\nexport const useCalendar = (props: ResolvedCalendarProps) => {\n  const { monthsToShow, firstDayOfWeek, locale, minDate, maxDate, isDateDisabled } = props;\n\n  const today = useMemo(() => normalizeDate(new Date()), []);\n  const state = useCalendarState(props, today);\n  const gridRef = useAutoFocusGrid(props.autoFocus);\n\n  const monthMatrices = useVisibleMonths({\n    currentMonth: state.currentMonth,\n    monthsToShow,\n    firstDayOfWeek,\n  });\n\n  const weekdayNames = useMemo(\n    () => getWeekdayNames(locale, firstDayOfWeek),\n    [locale, firstDayOfWeek],\n  );\n\n  const isDisabled = useCallback(\n    (date: Date) => isDateDisabledBy({ date, minDate, maxDate, isDateDisabled }),\n    [minDate, maxDate, isDateDisabled],\n  );\n\n  const { setCurrentMonth } = state;\n  const goToPreviousMonth = useCallback(\n    () => setCurrentMonth((prev) => addMonths(prev, -1)),\n    [setCurrentMonth],\n  );\n  const goToNextMonth = useCallback(\n    () => setCurrentMonth((prev) => addMonths(prev, 1)),\n    [setCurrentMonth],\n  );\n\n  const handleDateClick = useDateClick({\n    props,\n    isDisabled,\n    setFocusedDate: state.setFocusedDate,\n  });\n\n  const { handleDateMouseEnter, handleDateMouseLeave } = useHoverHandlers({\n    selectionMode: props.selectionMode,\n    range: props.range,\n    isDisabled,\n    setHoveredDate: state.setHoveredDate,\n  });\n\n  const handleKeyDown = useKeyboardHandler({\n    focusedDate: state.focusedDate,\n    firstDayOfWeek,\n    currentMonth: state.currentMonth,\n    handleDateClick,\n    setFocusedDate: state.setFocusedDate,\n    setCurrentMonth: state.setCurrentMonth,\n    setHoveredDate: state.setHoveredDate,\n  });\n\n  return {\n    gridRef,\n    today,\n    focusedDate: state.focusedDate,\n    hoveredDate: state.hoveredDate,\n    monthMatrices,\n    weekdayNames,\n    isDisabled,\n    goToPreviousMonth,\n    goToNextMonth,\n    handleDateClick,\n    handleDateMouseEnter,\n    handleDateMouseLeave,\n    handleKeyDown,\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;AACA,SAAS,aAAa,WAAW,SAAS,QAAQ,gBAAgB;AAOlE,IAAM,eAAe,CAAC,SAAqB,IAAI,KAAK,KAAK,YAAY,GAAG,KAAK,SAAS,GAAG,CAAC;AAG1F,IAAM,eAAe,CAAC,OAA8B,UAAsB;AACxE,MAAI,MAAM,kBAAkB,YAAY,MAAM,MAAO,QAAO,cAAc,MAAM,KAAK;AACrF,MAAI,MAAM,kBAAkB,WAAW,MAAM,MAAM,MAAO,QAAO,cAAc,MAAM,MAAM,KAAK;AAChG,SAAO;AACT;AAEA,IAAM,mBAAmB,CAAC,OAA8B,UAAgB;AACtE,QAAM,CAAC,aAAa,cAAc,IAAI,SAAe,MAAM,aAAa,OAAO,KAAK,CAAC;AACrF,QAAM,CAAC,aAAa,cAAc,IAAI,SAAsB,IAAI;AAChE,QAAM,CAAC,cAAc,eAAe,IAAI,SAAe,MAAM,aAAa,WAAW,CAAC;AAEtF,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEA,IAAM,mBAAmB,CAAC,cAAuB;AAC/C,QAAM,UAAU,OAAuB,IAAI;AAE3C,YAAU,MAAM;AACd,QAAI,aAAa,QAAQ,QAAS,SAAQ,QAAQ,MAAM;AAAA,EAC1D,GAAG,CAAC,SAAS,CAAC;AAEd,SAAO;AACT;AAEA,IAAM,mBAAmB,CAAC;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AACF,MAKE,QAAQ,MAAM;AACZ,QAAM,WAA0B,CAAC;AACjC,MAAI,SAAS;AAEb,WAAS,IAAI,GAAG,IAAI,cAAc,KAAK;AACrC,aAAS,KAAK,oBAAoB,OAAO,SAAS,GAAG,OAAO,YAAY,GAAG,cAAc,CAAC;AAC1F,aAAS,UAAU,QAAQ,CAAC;AAAA,EAC9B;AAEA,SAAO;AACT,GAAG,CAAC,cAAc,cAAc,cAAc,CAAC;AAIjD,IAAM,eAAe,CAAC;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AACF,MAIM;AACJ,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,SAAO;AAAA,IACL,CAAC,SAAe;AACd,UAAI,WAAW,IAAI,EAAG;AAEtB,YAAM,YAAY,cAAc,IAAI;AACpC,qBAAe,SAAS;AAExB,UAAI,kBAAkB,UAAU;AAC9B,mBAAW,SAAS;AACpB;AAAA,MACF;AAEA,YAAM,OAAO,cAAc;AAAA,QACzB,OAAO,MAAM;AAAA,QACb,KAAK,MAAM;AAAA,QACX;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAED,UAAI,KAAK,SAAS,WAAY;AAE9B,UAAI,KAAK,SAAS,WAAY,iBAAgB,KAAK,KAAK;AACxD,kCAA4B,KAAK,KAAK;AAAA,IACxC;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAGA,IAAM,mBAAmB,CAAC;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAKM;AACJ,QAAM,uBAAuB;AAAA,IAC3B,CAAC,SAAe;AACd,UAAI,kBAAkB,WAAW,MAAM,SAAS,CAAC,MAAM,OAAO,CAAC,WAAW,IAAI,GAAG;AAC/E,uBAAe,cAAc,IAAI,CAAC;AAAA,MACpC;AAAA,IACF;AAAA,IACA,CAAC,eAAe,OAAO,YAAY,cAAc;AAAA,EACnD;AAEA,QAAM,uBAAuB,YAAY,MAAM,eAAe,IAAI,GAAG,CAAC,cAAc,CAAC;AAErF,SAAO,EAAE,sBAAsB,qBAAqB;AACtD;AAEA,IAAM,qBAAqB,CAAC;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MASE;AAAA,EACE,CAAC,UAA+B;AAC9B,UAAM,EAAE,IAAI,IAAI;AAChB,UAAM,QAAQ,cAAc,KAAK,aAAa,EAAE,gBAAgB,UAAU,MAAM,SAAS,CAAC;AAE1F,QAAI,OAAO;AACT,YAAM,eAAe;AACrB,qBAAe,cAAc,KAAK,CAAC;AAGnC,YAAM,QAAQ,aAAa,KAAK;AAChC,UAAI,MAAM,QAAQ,MAAM,aAAa,QAAQ,EAAG,iBAAgB,KAAK;AACrE;AAAA,IACF;AAEA,QAAI,gBAAgB,SAAS,GAAG,GAAG;AACjC,YAAM,eAAe;AACrB,sBAAgB,WAAW;AAC3B;AAAA,IACF;AAEA,QAAI,QAAQ,UAAU;AACpB,YAAM,eAAe;AACrB,qBAAe,IAAI;AAAA,IACrB;AAAA,EACF;AAAA,EACA;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEK,IAAM,cAAc,CAAC,UAAiC;AAC3D,QAAM,EAAE,cAAc,gBAAgB,QAAQ,SAAS,SAAS,eAAe,IAAI;AAEnF,QAAM,QAAQ,QAAQ,MAAM,cAAc,oBAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACzD,QAAM,QAAQ,iBAAiB,OAAO,KAAK;AAC3C,QAAM,UAAU,iBAAiB,MAAM,SAAS;AAEhD,QAAM,gBAAgB,iBAAiB;AAAA,IACrC,cAAc,MAAM;AAAA,IACpB;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,eAAe;AAAA,IACnB,MAAM,gBAAgB,QAAQ,cAAc;AAAA,IAC5C,CAAC,QAAQ,cAAc;AAAA,EACzB;AAEA,QAAM,aAAa;AAAA,IACjB,CAAC,SAAe,iBAAiB,EAAE,MAAM,SAAS,SAAS,eAAe,CAAC;AAAA,IAC3E,CAAC,SAAS,SAAS,cAAc;AAAA,EACnC;AAEA,QAAM,EAAE,gBAAgB,IAAI;AAC5B,QAAM,oBAAoB;AAAA,IACxB,MAAM,gBAAgB,CAAC,SAAS,UAAU,MAAM,EAAE,CAAC;AAAA,IACnD,CAAC,eAAe;AAAA,EAClB;AACA,QAAM,gBAAgB;AAAA,IACpB,MAAM,gBAAgB,CAAC,SAAS,UAAU,MAAM,CAAC,CAAC;AAAA,IAClD,CAAC,eAAe;AAAA,EAClB;AAEA,QAAM,kBAAkB,aAAa;AAAA,IACnC;AAAA,IACA;AAAA,IACA,gBAAgB,MAAM;AAAA,EACxB,CAAC;AAED,QAAM,EAAE,sBAAsB,qBAAqB,IAAI,iBAAiB;AAAA,IACtE,eAAe,MAAM;AAAA,IACrB,OAAO,MAAM;AAAA,IACb;AAAA,IACA,gBAAgB,MAAM;AAAA,EACxB,CAAC;AAED,QAAM,gBAAgB,mBAAmB;AAAA,IACvC,aAAa,MAAM;AAAA,IACnB;AAAA,IACA,cAAc,MAAM;AAAA,IACpB;AAAA,IACA,gBAAgB,MAAM;AAAA,IACtB,iBAAiB,MAAM;AAAA,IACvB,gBAAgB,MAAM;AAAA,EACxB,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,aAAa,MAAM;AAAA,IACnB,aAAa,MAAM;AAAA,IACnB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}