pixelize-design-library 2.4.2-beta.27 → 2.4.2-beta.29

package/dist/Components/Button/Button.styles.js

@@ -4,6 +4,7 @@ exports.Button = void 0;
 const accentText_1 = require("../../Theme/tokens/builders/accentText");
 const color_1 = require("../../Theme/tokens/builders/color");
 const gradientInk_1 = require("../../Theme/tokens/builders/gradientInk");
+const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
 /**
  * Outline/ghost/link text sits ON the canvas, so it needs a rung that stays readable there —
  * `[500]` is pinned dark enough to carry a white label on the solid variant and measures only
@@ -62,8 +63,19 @@ const darkerFill = (theme, colorScheme, step) => {
 };
 /** Label for the solid variant's filled bg — derived from THAT fill, since hover/active swap it. */
 const labelFor = (theme, fill) => (0, accentText_1.onFilled)(fill, theme.colors.white, theme.colors.black);
+/**
+ * The two-tone `:focus-visible` ring, from the palette's derived `focusRing` pair.
+ *
+ * Every variant spreads this. Before it, none of them defined `_focusVisible` at all, so every
+ * button in every consuming app fell through to Chakra's stock `shadows.outline` — one fixed blue
+ * that measured 1.83:1 on the canvas and 1.38:1 on a primary fill, failing WCAG 1.4.11 (3:1) on
+ * all nine brands. `focusRing.test.ts` is the gate that keeps this true.
+ */
+const focusRing = (theme) => (0, focusRing_styles_1.focusVisibleStyles)(theme.colors);
 exports.Button = {
-    baseStyle: () => ({
+    // The ring is repeated on every variant below AND here, so a variant name this file does not
+    // define (a consumer's own, or an `IconButton` falling through) still gets an indicator.
+    baseStyle: ({ theme }) => ({
         borderRadius: "lg",
         fontWeight: 500,
         fontSize: "1rem",
@@ -72,6 +84,7 @@ exports.Button = {
             opacity: 0.6,
             cursor: "not-allowed",
         },
+        ...focusRing(theme),
     }),
     variants: {
         solid: ({ theme, colorScheme = "primary" }) => {
@@ -104,6 +117,7 @@ exports.Button = {
                         color: hoverLabel,
                     },
                 },
+                ...focusRing(theme),
             };
         },
         outline: ({ theme, colorScheme = "primary" }) => {
@@ -133,6 +147,7 @@ exports.Button = {
                     // bg: theme.colors[colorScheme][500],
                     color: ink,
                 },
+                ...focusRing(theme),
             };
         },
         ghost: ({ theme, colorScheme = "primary" }) => ({
@@ -145,6 +160,7 @@ exports.Button = {
             _active: {
                 bg: onCanvasHoverBg(theme, colorScheme, 24),
             },
+            ...focusRing(theme),
         }),
         link: ({ theme, colorScheme = "primary" }) => ({
             color: onCanvasText(theme, colorScheme),
@@ -157,13 +173,16 @@ exports.Button = {
             _active: {
                 color: onCanvasText(theme, colorScheme),
             },
+            ...focusRing(theme),
         }),
-        unstyled: () => ({
+        // `unstyled` drops the fill, not the affordance: a focus indicator is not styling.
+        unstyled: ({ theme }) => ({
             bg: "transparent",
             color: "inherit",
             _hover: {
                 bg: "transparent",
             },
+            ...focusRing(theme),
         }),
         // Theme-based two-tone gradient: each theme defines its own `gradient` {from,to} pair.
         // Ignores colorScheme; hover/active shift brightness so it works for any pair.
@@ -190,6 +209,7 @@ exports.Button = {
                     filter: "brightness(0.92)",
                     _hover: { bgImage: bg, filter: "brightness(0.92)" },
                 },
+                ...focusRing(theme),
             };
         },
     },

package/dist/Components/DatePicker/CalendarPanel.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type DayStates, type RenderDayContent } from "./dayStates";
 export type CalendarPanelProps = {
     currentMonth: Date;
     setCurrentMonth: (updater: (prev: Date) => Date) => void;
@@ -19,6 +20,10 @@ export type CalendarPanelProps = {
     hoveredDate?: Date | null;
     onDayHover?: (d: Date | null) => void;
     renderWeekdays?: React.ReactNode;
+    /** Marks individual days (weekly off, holiday, …). See `dayStates.ts`. Omit for the plain grid. */
+    dayStates?: DayStates;
+    /** Custom content inside a day cell, replacing that day's built-in marker dot. */
+    renderDayContent?: RenderDayContent;
 };
 export declare const CalendarPanel: React.FC<CalendarPanelProps>;
 export default CalendarPanel;

package/dist/Components/DatePicker/CalendarPanel.js

@@ -11,7 +11,8 @@ const lucide_react_1 = require("lucide-react");
 const Button_1 = __importDefault(require("../Button/Button"));
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const accentText_1 = require("../../Theme/tokens/builders/accentText");
-const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate, tempRangeStart, tempRangeEnd, isSameDay, isBefore, isAfter, minDate, maxDate, disablePastDates, disableFutureDates, disableToday, onDaySelect, hoveredDate, onDayHover, renderWeekdays, }) => {
+const dayStates_1 = require("./dayStates");
+const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate, tempRangeStart, tempRangeEnd, isSameDay, isBefore, isAfter, minDate, maxDate, disablePastDates, disableFutureDates, disableToday, onDaySelect, hoveredDate, onDayHover, renderWeekdays, dayStates, renderDayContent, }) => {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const rangeBg = theme.colors.primary.opacity[16];
     const isViewingCurrentMonth = currentMonth.getFullYear() === today.getFullYear() &&
@@ -51,6 +52,7 @@ const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate
         },
     };
     const renderDays = () => {
+        var _a;
         const monthStart = (0, date_fns_1.startOfMonth)(currentMonth);
         const monthEnd = (0, date_fns_1.endOfMonth)(currentMonth);
         const startDate = (0, date_fns_1.startOfWeek)(monthStart);
@@ -69,12 +71,17 @@ const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate
                 const isSelected = !!(!isRange && tempDate && isSameDay(thisDay, tempDate));
                 const isTentativeEnd = isEnd && isTentative;
                 const circleSolid = !!(isSelected || (isRange && isStart) || (isEnd && !isTentative));
+                // Marking is not disabling: only the `disabled` state key blocks selection, and only
+                // because the caller asked for it by name.
+                const states = (_a = dayStates === null || dayStates === void 0 ? void 0 : dayStates(thisDay)) !== null && _a !== void 0 ? _a : [];
+                const stateVisual = states.length ? (0, dayStates_1.resolveDayStateVisual)(states, theme.colors) : null;
                 const disabled = !isInCurrentMonth ||
                     !!(minDate && isBefore(thisDay, minDate)) ||
                     !!(maxDate && isAfter(thisDay, maxDate)) ||
                     !!(disablePastDates && isBefore(thisDay, today) && !isSameDay(thisDay, today)) ||
                     !!(disableFutureDates && isAfter(thisDay, today) && !isSameDay(thisDay, today)) ||
-                    !!(disableToday && isToday);
+                    !!(disableToday && isToday) ||
+                    !!(stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.blocksSelection);
                 // Connected range band painted on the cell background; start/end use a
                 // half gradient so the band meets the solid day circle cleanly.
                 let cellBg;
@@ -88,6 +95,9 @@ const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate
                     else if (isEnd)
                         cellBg = `linear-gradient(to right, ${rangeBg} 50%, transparent 50%)`;
                 }
+                // Selection feedback outranks a state tint — the band is what tells the user what they picked.
+                if (!cellBg && (stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.cellBg))
+                    cellBg = stateVisual.cellBg;
                 // Solid fill (selected/range-endpoint) needs the ink checked against that
                 // specific fill — `primary[500]` doesn't reliably clear AA for white text on
                 // every brand/mode (same gap the solid Button variant already accounts for).
@@ -108,11 +118,20 @@ const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate
                         : isToday
                             ? `1px solid ${theme.colors.primary[300]}`
                             : "1px solid transparent";
-                days.push((0, jsx_runtime_1.jsx)(react_1.Box, { h: "2rem", display: "flex", alignItems: "center", justifyContent: "center", style: cellBg ? { background: cellBg } : undefined, children: (0, jsx_runtime_1.jsx)(react_1.Box, { as: "button", type: "button", disabled: disabled, onClick: () => !disabled && onDaySelect(new Date(thisDay)), onMouseEnter: () => !disabled && (onDayHover === null || onDayHover === void 0 ? void 0 : onDayHover(new Date(thisDay))), w: "1.75rem", h: "1.75rem", borderRadius: "full", display: "flex", alignItems: "center", justifyContent: "center", fontSize: "0.8125rem", fontWeight: circleSolid ? 600 : 500, lineHeight: "1", cursor: disabled ? "not-allowed" : "pointer", bg: circleSolid ? solidFill : "transparent", color: circleColor, border: circleBorder, transition: "background 0.12s, color 0.12s", _hover: disabled
+                // A filled circle owns its own ink (checked against that fill by `onFilled`), so a state
+                // never repaints a selected day — it would undo that contrast guarantee.
+                const dayColor = !circleSolid && (stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.color) ? stateVisual.color : circleColor;
+                const dayBorder = !circleSolid && (stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.border) ? stateVisual.border : circleBorder;
+                const customContent = renderDayContent ? renderDayContent(thisDay, states) : null;
+                const markerColor = customContent == null && (stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.markerColor) ? stateVisual.markerColor : null;
+                const hasDayOverlay = customContent != null || markerColor != null;
+                days.push((0, jsx_runtime_1.jsx)(react_1.Box, { h: "2rem", display: "flex", alignItems: "center", justifyContent: "center", style: cellBg ? { background: cellBg } : undefined, children: (0, jsx_runtime_1.jsxs)(react_1.Box, { as: "button", type: "button", disabled: disabled, className: dayStates ? (0, dayStates_1.dayStateClassName)(states) : undefined, "aria-label": dayStates ? (0, dayStates_1.dayAccessibleName)((0, date_fns_1.format)(thisDay, "d MMMM yyyy"), states) : undefined, onClick: () => !disabled && onDaySelect(new Date(thisDay)), onMouseEnter: () => !disabled && (onDayHover === null || onDayHover === void 0 ? void 0 : onDayHover(new Date(thisDay))), position: hasDayOverlay ? "relative" : undefined, w: "1.75rem", h: "1.75rem", borderRadius: "full", display: "flex", alignItems: "center", justifyContent: "center", fontSize: "0.8125rem", fontWeight: circleSolid ? 600 : 500, lineHeight: "1", cursor: disabled ? "not-allowed" : "pointer", bg: circleSolid ? solidFill : "transparent", color: dayColor, textDecoration: (stateVisual === null || stateVisual === void 0 ? void 0 : stateVisual.strikethrough) ? "line-through" : undefined, border: dayBorder, transition: "background 0.12s, color 0.12s", _hover: disabled
                             ? {}
                             : circleSolid
                                 ? { bg: solidHoverFill, color: circleHoverColor }
-                                : { bg: rangeBg }, children: (0, date_fns_1.format)(thisDay, "d") }) }, thisDay.toString()));
+                                : { bg: rangeBg }, children: [(0, date_fns_1.format)(thisDay, "d"), hasDayOverlay && ((0, jsx_runtime_1.jsx)(react_1.Box, { as: "span", className: `${dayStates_1.DAY_CLASS}__content`, position: "absolute", left: 0, right: 0, bottom: "0.0625rem", display: "flex", alignItems: "flex-end", justifyContent: "center", lineHeight: "1", fontSize: "0.5rem", 
+                                // The overlay is decoration: clicks belong to the day button under it.
+                                pointerEvents: "none", children: customContent !== null && customContent !== void 0 ? customContent : ((0, jsx_runtime_1.jsx)(react_1.Box, { as: "span", className: `${dayStates_1.DAY_CLASS}__marker`, w: "0.25rem", h: "0.25rem", borderRadius: "full", bg: markerColor })) }))] }) }, thisDay.toString()));
                 day = (0, date_fns_1.addDays)(day, 1);
             }
             rows.push((0, jsx_runtime_1.jsx)(react_1.Grid, { templateColumns: "repeat(7, 1fr)", gap: 0, children: days }, day.toString()));

package/dist/Components/DatePicker/DatePickerProps.d.ts

@@ -1,3 +1,4 @@
+import type { DayStates, RenderDayContent } from "./dayStates";
 export type PickerType = "date" | "time" | "datetime";
 export type BaseDatePickerProps = {
     id?: string;
@@ -40,6 +41,26 @@ export type RangeDatePickerProps = BaseDatePickerProps & {
     /** Alias for `selectedDate` (legacy / form libraries). */
     value?: RangeDate | null;
     onChange: (range: RangeDate | null) => void;
+    /**
+     * Marks individual days with zero or more state keys — `["weekly-off"]`, `["Onam", "holiday"]`,
+     * `["excluded"]`. The keys in `DAY_STATE_KEYS` (`weekly-off`, `holiday`, `optional-holiday`,
+     * `excluded`, `disabled`) carry built-in, token-driven styling; any other key is announced to a
+     * screen reader but left unstyled, which is how a day gets named without a second prop.
+     *
+     * Marking is not disabling: a marked day stays selectable unless the caller also returns
+     * `"disabled"`, or blocks the day with `minDate`/`maxDate`/`disablePastDates`/`disableFutureDates`.
+     *
+     * Supplying this also spells each day's accessible name out in full — "16 September 2025, Onam,
+     * holiday" instead of "16". Called once per rendered day (42 per month), so keep it cheap and pure.
+     */
+    dayStates?: DayStates;
+    /**
+     * Custom content rendered inside the day cell, centred under the day number — a dot, a short
+     * label, a tooltip trigger. Receives that day's resolved state keys. Returning a node replaces
+     * the built-in marker dot for that day; the number, the accessible name and hit target are
+     * unchanged (the overlay does not take pointer events).
+     */
+    renderDayContent?: RenderDayContent;
 };
 export type DatePickerProps = SingleDatePickerProps | RangeDatePickerProps;
 export type TimePickerProps = {

package/dist/Components/DatePicker/RangeDatePicker.js

@@ -25,7 +25,7 @@ const setTimeFrom = (base, time) => {
 };
 const RangeDatePicker = (props) => {
     var _a, _b, _c, _d;
-    const { id, name, label, isRequired, isInformation, informationMessage, error, errorMessage, helperText, placeholderText, dateFormat = "dd/MM/yyyy", minDate, maxDate, disableFutureDates, disablePastDates, autoComplete = "off", disabled, width = "100%", disableToday = false, size = "md", } = props;
+    const { id, name, label, isRequired, isInformation, informationMessage, error, errorMessage, helperText, placeholderText, dateFormat = "dd/MM/yyyy", minDate, maxDate, disableFutureDates, disablePastDates, autoComplete = "off", disabled, width = "100%", disableToday = false, size = "md", dayStates, renderDayContent, } = props;
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const sizeKey = typeof size === "string" ? size : "md";
     const calendarIconPx = (0, textInputIconSize_1.getTextInputIconSizePx)(sizeKey);
@@ -181,7 +181,7 @@ const RangeDatePicker = (props) => {
                                         }, cursor: "pointer" }), (0, jsx_runtime_1.jsx)(react_2.InputRightElement, { height: "100%", display: "flex", alignItems: "center", pointerEvents: "auto", style: { cursor: "pointer" }, onClick: () => (isOpen ? onClose() : handleOpen()), children: (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", sx: calendarIconWrapperSx, children: (0, jsx_runtime_1.jsx)(lucide_react_1.CalendarIcon, { size: calendarIconPx, color: theme.colors.textMuted }) }) })] }) }) }), (0, jsx_runtime_1.jsx)(react_2.PopoverContent, { w: "18rem", maxW: "18rem", p: 3, ref: popoverRef, boxShadow: "lg", borderRadius: "xl", bg: theme.colors.background[50], children: (0, jsx_runtime_1.jsxs)(react_2.PopoverBody, { p: 0, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { display: "flex", flexWrap: "wrap", gap: 2, mb: 3, children: presets.map((p) => ((0, jsx_runtime_1.jsx)(Button_1.default, { size: "xs", variant: "outline", colorScheme: "gray", sx: { flex: "1 1 auto" }, onClick: () => {
                                             const [from, to] = p.getRange();
                                             applyPreset(from, to);
-                                        }, children: p.label }, p.label))) }), (0, jsx_runtime_1.jsx)(CalendarPanel_1.default, { currentMonth: currentMonth, setCurrentMonth: (updater) => setCurrentMonthState((prev) => updater(prev)), today: today, isRange: true, tempDate: null, tempRangeStart: tempRangeStart, tempRangeEnd: tempRangeEnd, hoveredDate: hoveredDate, onDayHover: setHoveredDate, isSameDay: date_fns_1.isSameDay, isBefore: date_fns_1.isBefore, isAfter: date_fns_1.isAfter, minDate: minDate, maxDate: maxDate, disablePastDates: disablePastDates, disableFutureDates: disableFutureDates, disableToday: disableToday, onDaySelect: handleDaySelect }), formatHasTime && ((0, jsx_runtime_1.jsxs)(react_2.Box, { mt: 3, display: "grid", gridTemplateColumns: "1fr", gap: 2, children: [(0, jsx_runtime_1.jsxs)(react_2.Box, { children: [(0, jsx_runtime_1.jsx)(react_2.Box, { fontSize: "xs", color: theme.colors.textMuted, mb: 1, children: "Start time" }), shouldUseSelectTimePicker ? ((0, jsx_runtime_1.jsx)(TimePicker_1.default, { date: startTimeBaseDate, onChange: (updated) => {
+                                        }, children: p.label }, p.label))) }), (0, jsx_runtime_1.jsx)(CalendarPanel_1.default, { currentMonth: currentMonth, setCurrentMonth: (updater) => setCurrentMonthState((prev) => updater(prev)), today: today, isRange: true, tempDate: null, tempRangeStart: tempRangeStart, tempRangeEnd: tempRangeEnd, hoveredDate: hoveredDate, onDayHover: setHoveredDate, isSameDay: date_fns_1.isSameDay, isBefore: date_fns_1.isBefore, isAfter: date_fns_1.isAfter, minDate: minDate, maxDate: maxDate, disablePastDates: disablePastDates, disableFutureDates: disableFutureDates, disableToday: disableToday, onDaySelect: handleDaySelect, dayStates: dayStates, renderDayContent: renderDayContent }), formatHasTime && ((0, jsx_runtime_1.jsxs)(react_2.Box, { mt: 3, display: "grid", gridTemplateColumns: "1fr", gap: 2, children: [(0, jsx_runtime_1.jsxs)(react_2.Box, { children: [(0, jsx_runtime_1.jsx)(react_2.Box, { fontSize: "xs", color: theme.colors.textMuted, mb: 1, children: "Start time" }), shouldUseSelectTimePicker ? ((0, jsx_runtime_1.jsx)(TimePicker_1.default, { date: startTimeBaseDate, onChange: (updated) => {
                                                         if (!tempRangeStart) {
                                                             setTempRangeStart(updated);
                                                             return;

package/dist/Components/DatePicker/dayStates.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Day-state marking for the calendar grid.
+ *
+ * A *state* is a key describing what a single day MEANS in the caller's domain — a weekly off,
+ * a public holiday, a day excluded from a leave count. It is deliberately separate from
+ * disabling: a marked day stays selectable unless the caller also returns the `"disabled"` key
+ * (or blocks the day through `minDate`/`maxDate`/`disablePastDates`/`disableFutureDates`).
+ *
+ * Every key returned reaches a screen reader. Only the keys in `DAY_STATE_KEYS` also carry
+ * built-in styling, so a caller can return a free-text key ("Onam") purely to have it announced
+ * alongside the recognised one: `["Onam", "holiday"]` → "16 September 2025, Onam, holiday".
+ *
+ * Colour comes from the palette only — every visual below is a function of `PaletteProps`, so a
+ * marked day follows the active light/dark palette like the rest of `CalendarPanel`.
+ */
+import type { ReactNode } from "react";
+import type { PaletteProps } from "../../Theme/tokens/types";
+/**
+ * The keys with built-in styling, in ascending precedence — when a day carries several, a later
+ * key's visual overrides the fields an earlier one set.
+ */
+export declare const DAY_STATE_KEYS: readonly ["weekly-off", "holiday", "optional-holiday", "excluded", "disabled"];
+export type DayStateKey = (typeof DAY_STATE_KEYS)[number];
+/** Returns zero or more state keys for a day. Unrecognised keys are announced, never styled. */
+export type DayStates = (date: Date) => string[] | undefined;
+/** Custom content rendered inside a day cell, beneath the day number. */
+export type RenderDayContent = (date: Date, states: string[]) => ReactNode;
+/** What a resolved set of states paints. Every field is optional — an absent field changes nothing. */
+export type DayStateVisual = {
+    /** Tint painted across the whole cell. The range band always wins over it. */
+    cellBg?: string;
+    /** Ink for the day number. Never applied to a selected/endpoint day, whose fill owns its ink. */
+    color?: string;
+    /** `border` shorthand for the day circle, replacing the today/tentative ring. */
+    border?: string;
+    /** Fill of the small marker dot under the number. `renderDayContent` replaces it. */
+    markerColor?: string;
+    /** Strikes the day number through — the "counted, but not really" states. */
+    strikethrough?: boolean;
+    /** The one state that also blocks selection. Marking alone never does. */
+    blocksSelection?: boolean;
+};
+export declare const isDayStateKey: (key: string) => key is DayStateKey;
+/** Merges every recognised state in `DAY_STATE_KEYS` order, so precedence never depends on caller order. */
+export declare const resolveDayStateVisual: (states: string[], colors: PaletteProps) => DayStateVisual;
+/** Base class on every day button once `dayStates` is supplied. Consumers may style off it. */
+export declare const DAY_CLASS = "pxl-calendar-day";
+/** `["Onam", "holiday"]` → `"pxl-calendar-day pxl-calendar-day--onam pxl-calendar-day--holiday"`. */
+export declare const dayStateClassName: (states: string[]) => string;
+/** Human phrasing for the accessible name — every key, styled or not, in the caller's own order. */
+export declare const describeDayStates: (states: string[]) => string;
+/**
+ * The day's accessible name. The date is spelled out because "16" alone tells a screen-reader
+ * user nothing, and the states follow it so the marking is heard, not only seen.
+ */
+export declare const dayAccessibleName: (formattedDate: string, states: string[]) => string;

package/dist/Components/DatePicker/dayStates.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dayAccessibleName = exports.describeDayStates = exports.dayStateClassName = exports.DAY_CLASS = exports.resolveDayStateVisual = exports.isDayStateKey = exports.DAY_STATE_KEYS = void 0;
+/**
+ * The keys with built-in styling, in ascending precedence — when a day carries several, a later
+ * key's visual overrides the fields an earlier one set.
+ */
+exports.DAY_STATE_KEYS = [
+    "weekly-off",
+    "holiday",
+    "optional-holiday",
+    "excluded",
+    "disabled",
+];
+/**
+ * Token roles, not rungs (see `Theme/THEME-CONTRACT.md`):
+ * - a non-working day is a *surface* step down plus muted ink — `backgroundColor.muted` / `textMuted`
+ * - a holiday is *status ink*, so `semanticText.<tone>`, never the `semantic.<tone>[500]` fill rung
+ * - an optional holiday is the same tone family one step less certain: warning + a dashed ring
+ * - an unavailable day is the `disabled` ramp, the only ramp whose job is exactly this
+ */
+const VISUALS = {
+    "weekly-off": (colors) => ({
+        cellBg: colors.backgroundColor.muted,
+        color: colors.textMuted,
+    }),
+    holiday: (colors) => ({
+        color: colors.semanticText.info,
+        markerColor: colors.semanticText.info,
+    }),
+    "optional-holiday": (colors) => ({
+        color: colors.semanticText.warning,
+        markerColor: colors.semanticText.warning,
+        border: `1px dashed ${colors.semanticText.warning}`,
+    }),
+    excluded: (colors) => ({
+        color: colors.textMuted,
+        strikethrough: true,
+    }),
+    disabled: (colors) => ({
+        color: colors.disabled[500],
+        blocksSelection: true,
+    }),
+};
+const isDayStateKey = (key) => exports.DAY_STATE_KEYS.includes(key);
+exports.isDayStateKey = isDayStateKey;
+/** Merges every recognised state in `DAY_STATE_KEYS` order, so precedence never depends on caller order. */
+const resolveDayStateVisual = (states, colors) => {
+    const visual = {};
+    for (const key of exports.DAY_STATE_KEYS) {
+        if (states.includes(key))
+            Object.assign(visual, VISUALS[key](colors));
+    }
+    return visual;
+};
+exports.resolveDayStateVisual = resolveDayStateVisual;
+/** Base class on every day button once `dayStates` is supplied. Consumers may style off it. */
+exports.DAY_CLASS = "pxl-calendar-day";
+const slug = (key) => key
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+/** `["Onam", "holiday"]` → `"pxl-calendar-day pxl-calendar-day--onam pxl-calendar-day--holiday"`. */
+const dayStateClassName = (states) => [
+    exports.DAY_CLASS,
+    ...states
+        .map(slug)
+        .filter(Boolean)
+        .map((key) => `${exports.DAY_CLASS}--${key}`),
+].join(" ");
+exports.dayStateClassName = dayStateClassName;
+/** Human phrasing for the accessible name — every key, styled or not, in the caller's own order. */
+const describeDayStates = (states) => states
+    .map((state) => ((0, exports.isDayStateKey)(state) ? state.replace(/-/g, " ") : state.trim()))
+    .filter(Boolean)
+    .join(", ");
+exports.describeDayStates = describeDayStates;
+/**
+ * The day's accessible name. The date is spelled out because "16" alone tells a screen-reader
+ * user nothing, and the states follow it so the marking is heard, not only seen.
+ */
+const dayAccessibleName = (formattedDate, states) => {
+    const described = (0, exports.describeDayStates)(states);
+    return described ? `${formattedDate}, ${described}` : formattedDate;
+};
+exports.dayAccessibleName = dayAccessibleName;

package/dist/Theme/assertPalette.d.ts

@@ -1,5 +1,5 @@
 import type { PaletteProps } from "./tokens/types";
-declare const REQUIRED_GROUPS: readonly ["gradient", "primary", "secondary", "tertiary", "transparent", "black", "white", "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan", "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder", "boxShadow", "sidebar", "boxborder", "border", "table", "disabled", "accentText", "textMuted", "semanticText", "onPrimary", "onSemantic"];
+declare const REQUIRED_GROUPS: readonly ["gradient", "primary", "secondary", "tertiary", "transparent", "black", "white", "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan", "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder", "boxShadow", "focusRing", "sidebar", "boxborder", "border", "table", "disabled", "accentText", "textMuted", "semanticText", "onPrimary", "onSemantic"];
 type Unlisted = Exclude<keyof PaletteProps, (typeof REQUIRED_GROUPS)[number]>;
 export type AllPaletteTokensListed = Unlisted extends never ? true : ["unlisted token", Unlisted];
 export declare const allPaletteTokensListed: AllPaletteTokensListed;

package/dist/Theme/assertPalette.js

@@ -5,8 +5,8 @@ const REQUIRED_GROUPS = [
     "gradient", "primary", "secondary", "tertiary", "transparent", "black", "white",
     "semantic", "gray", "red", "orange", "yellow", "green", "teal", "blue", "cyan",
     "purple", "pink", "backgroundColor", "background", "text", "header", "placeholder",
-    "boxShadow", "sidebar", "boxborder", "border", "table", "disabled", "accentText",
-    "textMuted", "semanticText", "onPrimary", "onSemantic",
+    "boxShadow", "focusRing", "sidebar", "boxborder", "border", "table", "disabled",
+    "accentText", "textMuted", "semanticText", "onPrimary", "onSemantic",
 ];
 exports.allPaletteTokensListed = true;
 const NESTED = [
@@ -17,6 +17,7 @@ const NESTED = [
         ]],
     ["semanticText", ["success", "error", "warning", "info"]],
     ["onSemantic", ["success", "error", "warning", "info"]],
+    ["focusRing", ["ring", "halo"]],
     ["backgroundColor", ["main", "base"]],
     ["boxShadow", ["primary", "default"]],
 ];

package/dist/Theme/chakra/createBrandTheme.js

@@ -10,6 +10,7 @@ const fonts_web_1 = __importDefault(require("./fonts.web"));
 const componentStyles_1 = require("./componentStyles");
 const accentText_1 = require("../tokens/builders/accentText");
 const scrollbar_1 = require("../tokens/builders/scrollbar");
+const focusRing_styles_1 = require("./focusRing.styles");
 /**
  * Builds a Chakra theme from a pure brand palette.
  *
@@ -27,6 +28,12 @@ const createBrandTheme = (palette, options = {}) => {
         colors: palette,
         ...fonts_web_1.default,
         ...common_web_1.default,
+        // `shadows.outline` is what Chakra's stock `_focusVisible` reaches for on EVERY component it
+        // themes. The primitive ships one hardcoded blue (`rgba(66,153,225,.6)`), which measured
+        // 1.83:1 on the lavender canvas and 1.38:1 on a primary button — below 1.4.11's 3:1 on all
+        // nine brands, in both modes. A primitive cannot know the palette; this is the first place
+        // that does, so the palette-derived ring is bound here and every stock focus state inherits it.
+        shadows: { ...common_web_1.default.shadows, outline: (0, focusRing_styles_1.focusRingShadow)(palette) },
     };
     return (0, react_1.extendTheme)({
         ...brand,

package/dist/Theme/chakra/focusRing.styles.d.ts

@@ -0,0 +1,52 @@
+import type { FocusRingTokens } from "../tokens/types";
+/**
+ * WEB binding for the `focusRing` token pair. The colours are derived in
+ * `tokens/builders/focusRing.ts` (pure, shared with the mobile library); the CSS shape —
+ * box-shadow bands, the forced-colors outline — is web-only and lives here.
+ */
+/** Inner band, in the surface tone: separates the ring from the control's own fill. */
+export declare const FOCUS_HALO_WIDTH = 2;
+/** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
+export declare const FOCUS_RING_WIDTH = 4;
+type WithFocusRing = {
+    focusRing: FocusRingTokens;
+};
+/**
+ * The two-tone ring as a single `box-shadow`. Drawn OUTSIDE the border box, so it costs no
+ * layout and never resizes the control — the reason this is a shadow and not an outline.
+ */
+export declare const focusRingShadow: (colors: WithFocusRing) => string;
+/**
+ * `:hover`, `:active` and `:focus-visible` all score the same specificity, so which one paints
+ * comes down to source order — and in the merged style object Chakra's own Button baseStyle
+ * registers `_focusVisible` BEFORE `_hover`. A focused button that is also hovered would then
+ * drop the ring for `_hover`'s `boxShadow: "sm"`. Stacking the pseudo-classes raises the
+ * specificity above both, so the ring survives whatever else the state repaints.
+ */
+export declare const FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
+/**
+ * `:focus-visible`, never `:focus` — a mouse click must not draw a ring.
+ *
+ * The transparent outline is not decoration: in Windows High Contrast / `forced-colors` mode
+ * box-shadows are dropped entirely, and a transparent outline is the one thing the OS repaints
+ * in its own focus colour. Without it, forced-colors users get no indicator at all.
+ */
+export declare const focusVisibleRing: (colors: WithFocusRing) => {
+    outline: string;
+    outlineOffset: string;
+    boxShadow: string;
+};
+/** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
+export declare const focusVisibleStyles: (colors: WithFocusRing) => {
+    _focusVisible: {
+        outline: string;
+        outlineOffset: string;
+        boxShadow: string;
+    };
+    "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible": {
+        outline: string;
+        outlineOffset: string;
+        boxShadow: string;
+    };
+};
+export {};

package/dist/Theme/chakra/focusRing.styles.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.focusVisibleStyles = exports.focusVisibleRing = exports.FOCUS_VISIBLE_OVER_STATE = exports.focusRingShadow = exports.FOCUS_RING_WIDTH = exports.FOCUS_HALO_WIDTH = void 0;
+/**
+ * WEB binding for the `focusRing` token pair. The colours are derived in
+ * `tokens/builders/focusRing.ts` (pure, shared with the mobile library); the CSS shape —
+ * box-shadow bands, the forced-colors outline — is web-only and lives here.
+ */
+/** Inner band, in the surface tone: separates the ring from the control's own fill. */
+exports.FOCUS_HALO_WIDTH = 2;
+/** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
+exports.FOCUS_RING_WIDTH = 4;
+/**
+ * The two-tone ring as a single `box-shadow`. Drawn OUTSIDE the border box, so it costs no
+ * layout and never resizes the control — the reason this is a shadow and not an outline.
+ */
+const focusRingShadow = (colors) => `0 0 0 ${exports.FOCUS_HALO_WIDTH}px ${colors.focusRing.halo}, ` +
+    `0 0 0 ${exports.FOCUS_RING_WIDTH}px ${colors.focusRing.ring}`;
+exports.focusRingShadow = focusRingShadow;
+/**
+ * `:hover`, `:active` and `:focus-visible` all score the same specificity, so which one paints
+ * comes down to source order — and in the merged style object Chakra's own Button baseStyle
+ * registers `_focusVisible` BEFORE `_hover`. A focused button that is also hovered would then
+ * drop the ring for `_hover`'s `boxShadow: "sm"`. Stacking the pseudo-classes raises the
+ * specificity above both, so the ring survives whatever else the state repaints.
+ */
+exports.FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
+/**
+ * `:focus-visible`, never `:focus` — a mouse click must not draw a ring.
+ *
+ * The transparent outline is not decoration: in Windows High Contrast / `forced-colors` mode
+ * box-shadows are dropped entirely, and a transparent outline is the one thing the OS repaints
+ * in its own focus colour. Without it, forced-colors users get no indicator at all.
+ */
+const focusVisibleRing = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: (0, exports.focusRingShadow)(colors),
+});
+exports.focusVisibleRing = focusVisibleRing;
+/** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
+const focusVisibleStyles = (colors) => {
+    const ring = (0, exports.focusVisibleRing)(colors);
+    return { _focusVisible: ring, [exports.FOCUS_VISIBLE_OVER_STATE]: ring };
+};
+exports.focusVisibleStyles = focusVisibleStyles;

package/dist/Theme/tokens/brands/index.js

@@ -46,6 +46,7 @@ const sidebarAccent_1 = require("../builders/sidebarAccent");
 const mutedText_1 = require("../builders/mutedText");
 const semanticText_1 = require("../builders/semanticText");
 const resolvedRungs_1 = require("../builders/resolvedRungs");
+const focusRing_1 = require("../builders/focusRing");
 const surfaceRungs_1 = require("../builders/surfaceRungs");
 /** Derived, never hand-written: a copied hex goes stale the moment a canvas moves. */
 const finalizeLightPalette = (source) => ({
@@ -56,9 +57,13 @@ const finalizeLightPalette = (source) => ({
     semanticText: (0, semanticText_1.buildSemanticText)(source.semantic, source.backgroundColor.main),
     onPrimary: (0, accentText_1.onFilled)(source.primary[500], source.white, source.black),
     onSemantic: (0, semanticText_1.buildOnSemantic)(source.semantic, source.white, source.black),
+    focusRing: (0, focusRing_1.buildFocusRing)(source),
 });
 exports.finalizeLightPalette = finalizeLightPalette;
-const resolveRungs = (palette) => (0, surfaceRungs_1.withSurfaceRungs)((0, resolvedRungs_1.withTableHoverRung)((0, resolvedRungs_1.withPlaceholderRung)((0, outlineRung_1.withOutlineRung)(palette))));
+// `withFocusRing` is outermost: it is the only step that reads `primary` and the surfaces
+// TOGETHER, so it must see both after every earlier step — and after a brand file's own
+// post-derivation overrides (zinc dark replaces `primary` and `background` wholesale).
+const resolveRungs = (palette) => (0, focusRing_1.withFocusRing)((0, surfaceRungs_1.withSurfaceRungs)((0, resolvedRungs_1.withTableHoverRung)((0, resolvedRungs_1.withPlaceholderRung)((0, outlineRung_1.withOutlineRung)(palette)))));
 const lightBrand = (source) => resolveRungs((0, exports.finalizeLightPalette)(source));
 /** Light palette per brand. `lavender` is the base the other six extend. */
 exports.lightPalettes = {

package/dist/Theme/tokens/brands/zinc/palette.dark.d.ts

@@ -197,6 +197,7 @@ declare const palette: {
     purple: import("../..").ColorScale;
     pink: import("../..").ColorScale;
     backgroundColor: import("../..").NamedSurfaces;
+    focusRing: import("../..").FocusRingTokens;
     sidebar: import("../..").SidebarTokens;
     semanticText: import("../..").SemanticTextTokens;
     textMuted: string;

package/dist/Theme/tokens/builders/buildDarkPalette.js

@@ -8,6 +8,7 @@ const accentText_1 = require("./accentText");
 const sidebarAccent_1 = require("./sidebarAccent");
 const mutedText_1 = require("./mutedText");
 const semanticText_1 = require("./semanticText");
+const focusRing_1 = require("./focusRing");
 /**
  * Derives a brand's dark palette from its light palette.
  *
@@ -246,6 +247,7 @@ function buildDarkPalette(light) {
     ]));
     const white = light.white;
     const primary = liftBrand(light.primary, white);
+    const background = fromTargets(hueSource, SURFACE_TARGETS, SURFACE_SAT);
     const semantic = {
         success: liftAccent(light.semantic.success, white),
         error: liftAccent(light.semantic.error, white),
@@ -276,7 +278,7 @@ function buildDarkPalette(light) {
         purple: (0, exports.reverseScale)(light.purple),
         pink: (0, exports.reverseScale)(light.pink),
         backgroundColor: namedSurfaces,
-        background: fromTargets(hueSource, SURFACE_TARGETS, SURFACE_SAT),
+        background,
         text: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT),
         header: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT + 2),
         placeholder: fromTargets(hueSource, PLACEHOLDER_TARGETS, PLACEHOLDER_SAT),
@@ -293,6 +295,9 @@ function buildDarkPalette(light) {
         semanticText: (0, semanticText_1.buildSemanticText)(semantic, namedSurfaces.main),
         onPrimary: (0, accentText_1.onFilled)(primary[500], light.white, light.black),
         onSemantic: (0, semanticText_1.buildOnSemantic)(semantic, light.white, light.black),
+        // The dark ring is derived from the LIFTED accent against the dark canvas, not copied from
+        // light: the two modes squeeze it from opposite sides, so a shared value fails one of them.
+        focusRing: (0, focusRing_1.buildFocusRing)({ primary, background, backgroundColor: namedSurfaces }),
         // Sidebar is already near-black in light mode, so it needs no inversion.
         sidebar: (0, sidebarAccent_1.withSidebarTokens)(light),
         boxShadow: {