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

package/dist/Theme/tokens/builders/focusRing.d.ts

@@ -0,0 +1,52 @@
+import type { FocusRingTokens, PaletteProps } from "../types";
+/**
+ * The nearest re-lighting of `hex` that clears `target` against EVERY backdrop at once.
+ *
+ * Not `settleAcross`: that folds one `liftToContrast` per surface, and each lift walks AWAY from
+ * the surface it was handed. That is correct when every backdrop sits on the same side of the ink
+ * (its case — a set of light surfaces, or a set of dark ones), and wrong here, where a focus ring
+ * is squeezed BETWEEN a near-white canvas and a mid-dark button fill: the lift against the fill
+ * walks straight back across the canvas it had just cleared. Seeding `settleAcross` with
+ * `primary[500]` measured 1.08-1.99 on the light canvas for every brand for exactly that reason.
+ *
+ * Walking outward from the seed and testing every backdrop at each step keeps the result the
+ * CLOSEST passing colour to the brand accent, so the ring still reads as brand chrome. Contrast is
+ * a function of relative luminance alone, and lightness sweeps luminance monotonically from 0 to 1,
+ * so if any colour on this hue clears the set, this finds it.
+ */
+export declare function settleBetween(hex: string, backdrops: readonly string[], target?: number): string;
+/** Everything the ring is derived from. A `PaletteProps` satisfies it; so does a brand source. */
+export type FocusRingSource = Pick<PaletteProps, "primary" | "background" | "backgroundColor">;
+/**
+ * The three backdrops a focused button's ring is actually drawn against: the page canvas, a card
+ * surface, and — because a solid button's ring sits directly against its own fill — `primary[500]`.
+ *
+ * Deliberately NOT every named surface. `muted`/`accent`/`quaternary` are mid-tone, and a single
+ * band asked to clear those AND a dark brand fill has no solution at any hue — contrast is
+ * luminance alone, and `skyline`/`storefront` come out with an empty band. That is what the second
+ * tone is for: `halo` owns the fill-side adjacency instead.
+ */
+export declare const focusRingBackdrops: (source: FocusRingSource) => string[];
+/**
+ * The two-tone `:focus-visible` indicator.
+ *
+ * Chakra's stock ring (`shadows.outline`, a fixed `rgba(66,153,225,.6)`) measured 1.83:1 on the
+ * lavender canvas and 1.38:1 on a primary button — a focus indicator you cannot see, on all nine
+ * brands. It is one hardcoded blue, so no palette could have saved it.
+ *
+ * `halo` is the surface tone, drawn as the inner band so the indicator separates from a filled
+ * control whatever `colorScheme` painted it. `ring` is the brand accent, walked to the nearest
+ * lightness that clears 3:1 on all three backdrops at once — including the halo, so the two tones
+ * are always told apart.
+ */
+export declare const buildFocusRing: (source: FocusRingSource) => FocusRingTokens;
+/**
+ * Re-derives the ring from the FINISHED palette, as the last step of the rung chain.
+ *
+ * `finalizeLightPalette` and `buildDarkPalette` seed it, but neither is the final word: a brand
+ * file may replace `primary` or `background` after the generic derivation runs — `zinc`'s dark
+ * palette replaces both, inverting the filled button to near-white — and a ring resolved against
+ * the pre-override values is then silently wrong. Same reason `withSurfaceRungs` re-lifts inks the
+ * finalizers already derived. `focusRing.test.ts` asserts this is a fixed point.
+ */
+export declare const withFocusRing: (palette: PaletteProps) => PaletteProps;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFocusRing = exports.buildFocusRing = exports.focusRingBackdrops = void 0;
+exports.settleBetween = settleBetween;
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+/** Same lightness granularity `buildDarkPalette` walks its accents at. */
+const LIGHTNESS_STEP = 0.5;
+/**
+ * The nearest re-lighting of `hex` that clears `target` against EVERY backdrop at once.
+ *
+ * Not `settleAcross`: that folds one `liftToContrast` per surface, and each lift walks AWAY from
+ * the surface it was handed. That is correct when every backdrop sits on the same side of the ink
+ * (its case — a set of light surfaces, or a set of dark ones), and wrong here, where a focus ring
+ * is squeezed BETWEEN a near-white canvas and a mid-dark button fill: the lift against the fill
+ * walks straight back across the canvas it had just cleared. Seeding `settleAcross` with
+ * `primary[500]` measured 1.08-1.99 on the light canvas for every brand for exactly that reason.
+ *
+ * Walking outward from the seed and testing every backdrop at each step keeps the result the
+ * CLOSEST passing colour to the brand accent, so the ring still reads as brand chrome. Contrast is
+ * a function of relative luminance alone, and lightness sweeps luminance monotonically from 0 to 1,
+ * so if any colour on this hue clears the set, this finds it.
+ */
+function settleBetween(hex, backdrops, target = outlineRung_1.AA_NON_TEXT) {
+    const clears = (candidate) => backdrops.every((backdrop) => (0, color_1.contrastRatio)(candidate, backdrop) >= target);
+    if (clears(hex))
+        return hex;
+    const { l } = (0, color_1.hexToHsl)(hex);
+    for (let step = LIGHTNESS_STEP; step <= 100; step += LIGHTNESS_STEP) {
+        const darker = (0, color_1.withLightness)(hex, l - step);
+        if (clears(darker))
+            return darker;
+        const lighter = (0, color_1.withLightness)(hex, l + step);
+        if (clears(lighter))
+            return lighter;
+    }
+    // Unreachable for every shipped brand (the gate proves it) — a brand whose fill and canvas are
+    // close enough to leave no gap would land here. Take the end that is least bad rather than throw
+    // at import time, and let `focusRing.test.ts` be what reports it.
+    const ends = [(0, color_1.withLightness)(hex, 0), (0, color_1.withLightness)(hex, 100)];
+    const worst = (candidate) => Math.min(...backdrops.map((backdrop) => (0, color_1.contrastRatio)(candidate, backdrop)));
+    return worst(ends[0]) >= worst(ends[1]) ? ends[0] : ends[1];
+}
+/**
+ * The three backdrops a focused button's ring is actually drawn against: the page canvas, a card
+ * surface, and — because a solid button's ring sits directly against its own fill — `primary[500]`.
+ *
+ * Deliberately NOT every named surface. `muted`/`accent`/`quaternary` are mid-tone, and a single
+ * band asked to clear those AND a dark brand fill has no solution at any hue — contrast is
+ * luminance alone, and `skyline`/`storefront` come out with an empty band. That is what the second
+ * tone is for: `halo` owns the fill-side adjacency instead.
+ */
+const focusRingBackdrops = (source) => [
+    source.backgroundColor.main,
+    source.background[50],
+    source.primary[500],
+];
+exports.focusRingBackdrops = focusRingBackdrops;
+/**
+ * The two-tone `:focus-visible` indicator.
+ *
+ * Chakra's stock ring (`shadows.outline`, a fixed `rgba(66,153,225,.6)`) measured 1.83:1 on the
+ * lavender canvas and 1.38:1 on a primary button — a focus indicator you cannot see, on all nine
+ * brands. It is one hardcoded blue, so no palette could have saved it.
+ *
+ * `halo` is the surface tone, drawn as the inner band so the indicator separates from a filled
+ * control whatever `colorScheme` painted it. `ring` is the brand accent, walked to the nearest
+ * lightness that clears 3:1 on all three backdrops at once — including the halo, so the two tones
+ * are always told apart.
+ */
+const buildFocusRing = (source) => {
+    const halo = settleBetween(source.background[50], [source.primary[500]]);
+    return {
+        halo,
+        ring: settleBetween(source.primary[500], [...(0, exports.focusRingBackdrops)(source), halo]),
+    };
+};
+exports.buildFocusRing = buildFocusRing;
+/**
+ * Re-derives the ring from the FINISHED palette, as the last step of the rung chain.
+ *
+ * `finalizeLightPalette` and `buildDarkPalette` seed it, but neither is the final word: a brand
+ * file may replace `primary` or `background` after the generic derivation runs — `zinc`'s dark
+ * palette replaces both, inverting the filled button to near-white — and a ring resolved against
+ * the pre-override values is then silently wrong. Same reason `withSurfaceRungs` re-lifts inks the
+ * finalizers already derived. `focusRing.test.ts` asserts this is a fixed point.
+ */
+const withFocusRing = (palette) => ({
+    ...palette,
+    focusRing: (0, exports.buildFocusRing)(palette),
+});
+exports.withFocusRing = withFocusRing;

package/dist/Theme/tokens/builders/index.d.ts

@@ -3,6 +3,7 @@ export * from "./buildBrandTokens";
 export * from "./buildDarkPalette";
 export * from "./chartColorsFromTheme";
 export * from "./color";
+export * from "./focusRing";
 export * from "./scrollbar";
 export * from "./gradientInk";
 export * from "./placeholderInk";

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

@@ -19,6 +19,7 @@ __exportStar(require("./buildBrandTokens"), exports);
 __exportStar(require("./buildDarkPalette"), exports);
 __exportStar(require("./chartColorsFromTheme"), exports);
 __exportStar(require("./color"), exports);
+__exportStar(require("./focusRing"), exports);
 __exportStar(require("./scrollbar"), exports);
 __exportStar(require("./gradientInk"), exports);
 __exportStar(require("./placeholderInk"), exports);

package/dist/Theme/tokens/builders/outlineRung.d.ts

@@ -12,8 +12,14 @@ export declare const AA_NON_TEXT = 3;
  * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
  * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
  * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
- * border carry the whole job: the fill, the label and the focus ring do that, and the focus
- * ring is still held to `AA_NON_TEXT`.
+ * border carry the whole job: the fill, the label and the focus ring do that.
+ *
+ * That defence was untrue when it was written. Buttons defined no `_focusVisible` at all, so the
+ * focus ring was Chakra's stock `shadows.outline` — a fixed blue measuring 1.38:1 on a primary
+ * button — and nothing in the library was held to `AA_NON_TEXT` at the moment of focus. It is
+ * true now: `focusRing` (`builders/focusRing.ts`) is derived per brand per mode and gated at 3:1
+ * on the canvas, on a card and on the button's own fill by `builders/focusRing.test.ts`. If that
+ * gate is ever relaxed, this constant loses its justification with it.
  */
 export declare const CHROME_BORDER = 1.5;
 export declare const CHROME_RULE = 1.31;

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

@@ -21,8 +21,14 @@ exports.AA_NON_TEXT = 3;
  * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
  * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
  * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
- * border carry the whole job: the fill, the label and the focus ring do that, and the focus
- * ring is still held to `AA_NON_TEXT`.
+ * border carry the whole job: the fill, the label and the focus ring do that.
+ *
+ * That defence was untrue when it was written. Buttons defined no `_focusVisible` at all, so the
+ * focus ring was Chakra's stock `shadows.outline` — a fixed blue measuring 1.38:1 on a primary
+ * button — and nothing in the library was held to `AA_NON_TEXT` at the moment of focus. It is
+ * true now: `focusRing` (`builders/focusRing.ts`) is derived per brand per mode and gated at 3:1
+ * on the canvas, on a card and on the button's own fill by `builders/focusRing.test.ts`. If that
+ * gate is ever relaxed, this constant loses its justification with it.
  */
 exports.CHROME_BORDER = 1.5;
 // The resting rule between two surfaces — a card edge, a divider, a menu outline. Lighter than

package/dist/Theme/tokens/types.d.ts

@@ -65,6 +65,24 @@ export type SidebarTokens = {
     /** Status ink resolved against the RAIL. `semanticText` is canvas-relative, not rail. */
     semanticText: SemanticTextTokens;
 };
+/**
+ * The two-tone focus indicator. `ring` is the brand-toned band that carries WCAG 1.4.11
+ * against whatever is BEHIND the control; `halo` is the inner band drawn between the ring
+ * and the control's own fill, so the indicator stays visible on a filled button too.
+ *
+ * Two tones because one band cannot own both adjacencies. `ring` is resolved against three
+ * backdrops (canvas, card, `primary[500]`) and clears all three on every brand — but a button
+ * can be filled by any `colorScheme`, and widening the ring to cover the mid-tone named surfaces
+ * as well leaves `skyline` and `storefront` with no solution at any hue (contrast is luminance
+ * alone, and their bands come out empty). `halo` takes the fill-side adjacency instead, so the
+ * pair holds whatever the button is filled with and whatever it sits on.
+ */
+export type FocusRingTokens = {
+    /** Outer band. >=3:1 against the canvas, a card surface, and the control's own fill. */
+    ring: string;
+    /** Inner band, in the surface tone. >=3:1 against the fill it hugs and against `ring`. */
+    halo: string;
+};
 export type BoxShadowTokens = {
     primary: string;
     error: string;
@@ -102,6 +120,8 @@ export type PaletteProps = {
     header: ColorScale;
     placeholder: ColorScale;
     boxShadow: BoxShadowTokens;
+    /** Two-tone `:focus-visible` indicator, resolved to 3:1 (WCAG 1.4.11). Never hand-written. */
+    focusRing: FocusRingTokens;
     sidebar: SidebarTokens;
     boxborder: ColorScale;
     border: ColorScale;
@@ -125,7 +145,7 @@ export type PaletteProps = {
 };
 /** What a brand writes by hand; every token required, so a gap is a compile error. */
 /** Derived tokens are excluded — `finalizeLightPalette` resolves them per brand. */
-export type BrandPaletteSource = Omit<PaletteProps, "accentText" | "textMuted" | "semanticText" | "sidebar" | "onPrimary" | "onSemantic"> & {
+export type BrandPaletteSource = Omit<PaletteProps, "accentText" | "textMuted" | "semanticText" | "sidebar" | "onPrimary" | "onSemantic" | "focusRing"> & {
     sidebar: {
         background: ColorScale;
     };

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

@@ -1,6 +1,7 @@
 import { accentTextOnCanvas, isDarkCanvas, onFilled } from "../../Theme/tokens/builders/accentText.js";
 import { contrastRatio } from "../../Theme/tokens/builders/color.js";
 import { resolveGradient, gradientCss } from "../../Theme/tokens/builders/gradientInk.js";
+import { focusVisibleStyles } from "../../Theme/chakra/focusRing.styles.js";
 /**
  * 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
@@ -59,8 +60,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) => 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) => focusVisibleStyles(theme.colors);
 export const 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",
@@ -69,6 +81,7 @@ export const Button = {
             opacity: 0.6,
             cursor: "not-allowed",
         },
+        ...focusRing(theme),
     }),
     variants: {
         solid: ({ theme, colorScheme = "primary" }) => {
@@ -101,6 +114,7 @@ export const Button = {
                         color: hoverLabel,
                     },
                 },
+                ...focusRing(theme),
             };
         },
         outline: ({ theme, colorScheme = "primary" }) => {
@@ -130,6 +144,7 @@ export const Button = {
                     // bg: theme.colors[colorScheme][500],
                     color: ink,
                 },
+                ...focusRing(theme),
             };
         },
         ghost: ({ theme, colorScheme = "primary" }) => ({
@@ -142,6 +157,7 @@ export const Button = {
             _active: {
                 bg: onCanvasHoverBg(theme, colorScheme, 24),
             },
+            ...focusRing(theme),
         }),
         link: ({ theme, colorScheme = "primary" }) => ({
             color: onCanvasText(theme, colorScheme),
@@ -154,13 +170,16 @@ export const 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.
@@ -187,6 +206,7 @@ export const Button = {
                     filter: "brightness(0.92)",
                     _hover: { bgImage: bg, filter: "brightness(0.92)" },
                 },
+                ...focusRing(theme),
             };
         },
     },

package/dist/esm/Components/DatePicker/CalendarPanel.js

@@ -5,7 +5,8 @@ import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import Button from "../Button/Button.js";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { onFilled } from "../../Theme/tokens/builders/accentText.js";
-export const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, tempDate, tempRangeStart, tempRangeEnd, isSameDay, isBefore, isAfter, minDate, maxDate, disablePastDates, disableFutureDates, disableToday, onDaySelect, hoveredDate, onDayHover, renderWeekdays, }) => {
+import { DAY_CLASS, dayAccessibleName, dayStateClassName, resolveDayStateVisual, } from "./dayStates.js";
+export 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 = useCustomTheme();
     const rangeBg = theme.colors.primary.opacity[16];
     const isViewingCurrentMonth = currentMonth.getFullYear() === today.getFullYear() &&
@@ -45,6 +46,7 @@ export const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, t
         },
     };
     const renderDays = () => {
+        var _a;
         const monthStart = startOfMonth(currentMonth);
         const monthEnd = endOfMonth(currentMonth);
         const startDate = startOfWeek(monthStart);
@@ -63,12 +65,17 @@ export const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, t
                 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 ? 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;
@@ -82,6 +89,9 @@ export const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, t
                     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).
@@ -102,11 +112,20 @@ export const CalendarPanel = ({ currentMonth, setCurrentMonth, today, isRange, t
                         : isToday
                             ? `1px solid ${theme.colors.primary[300]}`
                             : "1px solid transparent";
-                days.push(_jsx(Box, { h: "2rem", display: "flex", alignItems: "center", justifyContent: "center", style: cellBg ? { background: cellBg } : undefined, children: _jsx(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(_jsx(Box, { h: "2rem", display: "flex", alignItems: "center", justifyContent: "center", style: cellBg ? { background: cellBg } : undefined, children: _jsxs(Box, { as: "button", type: "button", disabled: disabled, className: dayStates ? dayStateClassName(states) : undefined, "aria-label": dayStates ? dayAccessibleName(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: format(thisDay, "d") }) }, thisDay.toString()));
+                                : { bg: rangeBg }, children: [format(thisDay, "d"), hasDayOverlay && (_jsx(Box, { as: "span", className: `${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 : (_jsx(Box, { as: "span", className: `${DAY_CLASS}__marker`, w: "0.25rem", h: "0.25rem", borderRadius: "full", bg: markerColor })) }))] }) }, thisDay.toString()));
                 day = addDays(day, 1);
             }
             rows.push(_jsx(Grid, { templateColumns: "repeat(7, 1fr)", gap: 0, children: days }, day.toString()));

package/dist/esm/Components/DatePicker/RangeDatePicker.js

@@ -19,7 +19,7 @@ const setTimeFrom = (base, time) => {
 };
 export 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 = useCustomTheme();
     const sizeKey = typeof size === "string" ? size : "md";
     const calendarIconPx = getTextInputIconSizePx(sizeKey);
@@ -175,7 +175,7 @@ export const RangeDatePicker = (props) => {
                                         }, cursor: "pointer" }), _jsx(InputRightElement, { height: "100%", display: "flex", alignItems: "center", pointerEvents: "auto", style: { cursor: "pointer" }, onClick: () => (isOpen ? onClose() : handleOpen()), children: _jsx(Box, { as: "span", sx: calendarIconWrapperSx, children: _jsx(CalendarIcon, { size: calendarIconPx, color: theme.colors.textMuted }) }) })] }) }) }), _jsx(PopoverContent, { w: "18rem", maxW: "18rem", p: 3, ref: popoverRef, boxShadow: "lg", borderRadius: "xl", bg: theme.colors.background[50], children: _jsxs(PopoverBody, { p: 0, children: [_jsx(Box, { display: "flex", flexWrap: "wrap", gap: 2, mb: 3, children: presets.map((p) => (_jsx(Button, { 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))) }), _jsx(CalendarPanel, { currentMonth: currentMonth, setCurrentMonth: (updater) => setCurrentMonthState((prev) => updater(prev)), today: today, isRange: true, tempDate: null, tempRangeStart: tempRangeStart, tempRangeEnd: tempRangeEnd, hoveredDate: hoveredDate, onDayHover: setHoveredDate, isSameDay: isSameDay, isBefore: isBefore, isAfter: isAfter, minDate: minDate, maxDate: maxDate, disablePastDates: disablePastDates, disableFutureDates: disableFutureDates, disableToday: disableToday, onDaySelect: handleDaySelect }), formatHasTime && (_jsxs(Box, { mt: 3, display: "grid", gridTemplateColumns: "1fr", gap: 2, children: [_jsxs(Box, { children: [_jsx(Box, { fontSize: "xs", color: theme.colors.textMuted, mb: 1, children: "Start time" }), shouldUseSelectTimePicker ? (_jsx(TimePicker, { date: startTimeBaseDate, onChange: (updated) => {
+                                        }, children: p.label }, p.label))) }), _jsx(CalendarPanel, { currentMonth: currentMonth, setCurrentMonth: (updater) => setCurrentMonthState((prev) => updater(prev)), today: today, isRange: true, tempDate: null, tempRangeStart: tempRangeStart, tempRangeEnd: tempRangeEnd, hoveredDate: hoveredDate, onDayHover: setHoveredDate, isSameDay: isSameDay, isBefore: isBefore, isAfter: isAfter, minDate: minDate, maxDate: maxDate, disablePastDates: disablePastDates, disableFutureDates: disableFutureDates, disableToday: disableToday, onDaySelect: handleDaySelect, dayStates: dayStates, renderDayContent: renderDayContent }), formatHasTime && (_jsxs(Box, { mt: 3, display: "grid", gridTemplateColumns: "1fr", gap: 2, children: [_jsxs(Box, { children: [_jsx(Box, { fontSize: "xs", color: theme.colors.textMuted, mb: 1, children: "Start time" }), shouldUseSelectTimePicker ? (_jsx(TimePicker, { date: startTimeBaseDate, onChange: (updated) => {
                                                         if (!tempRangeStart) {
                                                             setTempRangeStart(updated);
                                                             return;

package/dist/esm/Components/DatePicker/dayStates.js

@@ -0,0 +1,79 @@
+/**
+ * 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 const 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,
+    }),
+};
+export const isDayStateKey = (key) => DAY_STATE_KEYS.includes(key);
+/** Merges every recognised state in `DAY_STATE_KEYS` order, so precedence never depends on caller order. */
+export const resolveDayStateVisual = (states, colors) => {
+    const visual = {};
+    for (const key of DAY_STATE_KEYS) {
+        if (states.includes(key))
+            Object.assign(visual, VISUALS[key](colors));
+    }
+    return visual;
+};
+/** Base class on every day button once `dayStates` is supplied. Consumers may style off it. */
+export const 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"`. */
+export const dayStateClassName = (states) => [
+    DAY_CLASS,
+    ...states
+        .map(slug)
+        .filter(Boolean)
+        .map((key) => `${DAY_CLASS}--${key}`),
+].join(" ");
+/** Human phrasing for the accessible name — every key, styled or not, in the caller's own order. */
+export const describeDayStates = (states) => states
+    .map((state) => (isDayStateKey(state) ? state.replace(/-/g, " ") : state.trim()))
+    .filter(Boolean)
+    .join(", ");
+/**
+ * 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 const dayAccessibleName = (formattedDate, states) => {
+    const described = describeDayStates(states);
+    return described ? `${formattedDate}, ${described}` : formattedDate;
+};

package/dist/esm/Theme/assertPalette.js

@@ -2,8 +2,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",
 ];
 export const allPaletteTokensListed = true;
 const NESTED = [
@@ -14,6 +14,7 @@ const NESTED = [
         ]],
     ["semanticText", ["success", "error", "warning", "info"]],
     ["onSemantic", ["success", "error", "warning", "info"]],
+    ["focusRing", ["ring", "halo"]],
     ["backgroundColor", ["main", "base"]],
     ["boxShadow", ["primary", "default"]],
 ];

package/dist/esm/Theme/chakra/createBrandTheme.js

@@ -4,6 +4,7 @@ import fonts from "./fonts.web.js";
 import { componentStyles } from "./componentStyles.js";
 import { onFilled } from "../tokens/builders/accentText.js";
 import { globalScrollbarStyles } from "../tokens/builders/scrollbar.js";
+import { focusRingShadow } from "./focusRing.styles.js";
 /**
  * Builds a Chakra theme from a pure brand palette.
  *
@@ -21,6 +22,12 @@ export const createBrandTheme = (palette, options = {}) => {
         colors: palette,
         ...fonts,
         ...common,
+        // `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.shadows, outline: focusRingShadow(palette) },
     };
     return extendTheme({
         ...brand,

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

@@ -0,0 +1,40 @@
+/**
+ * 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 const FOCUS_HALO_WIDTH = 2;
+/** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
+export const 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.
+ */
+export const focusRingShadow = (colors) => `0 0 0 ${FOCUS_HALO_WIDTH}px ${colors.focusRing.halo}, ` +
+    `0 0 0 ${FOCUS_RING_WIDTH}px ${colors.focusRing.ring}`;
+/**
+ * `: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 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 const focusVisibleRing = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: focusRingShadow(colors),
+});
+/** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
+export const focusVisibleStyles = (colors) => {
+    const ring = focusVisibleRing(colors);
+    return { _focusVisible: ring, [FOCUS_VISIBLE_OVER_STATE]: ring };
+};

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

@@ -22,6 +22,7 @@ import { withSidebarTokens } from "../builders/sidebarAccent.js";
 import { buildMutedText } from "../builders/mutedText.js";
 import { buildSemanticText, buildOnSemantic } from "../builders/semanticText.js";
 import { withPlaceholderRung, withTableHoverRung } from "../builders/resolvedRungs.js";
+import { buildFocusRing, withFocusRing } from "../builders/focusRing.js";
 import { withSurfaceRungs } from "../builders/surfaceRungs.js";
 /** Derived, never hand-written: a copied hex goes stale the moment a canvas moves. */
 export const finalizeLightPalette = (source) => ({
@@ -32,10 +33,14 @@ export const finalizeLightPalette = (source) => ({
     semanticText: buildSemanticText(source.semantic, source.backgroundColor.main),
     onPrimary: onFilled(source.primary[500], source.white, source.black),
     onSemantic: buildOnSemantic(source.semantic, source.white, source.black),
+    focusRing: buildFocusRing(source),
 });
 export { lavender, meadow, radiant, skyline, slate, emerald, rosewood, storefront, zinc };
 export { lavenderDark, meadowDark, radiantDark, skylineDark, slateDark, emeraldDark, rosewoodDark, storefrontDark, zincDark, };
-const resolveRungs = (palette) => withSurfaceRungs(withTableHoverRung(withPlaceholderRung(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) => withFocusRing(withSurfaceRungs(withTableHoverRung(withPlaceholderRung(withOutlineRung(palette)))));
 const lightBrand = (source) => resolveRungs(finalizeLightPalette(source));
 /** Light palette per brand. `lavender` is the base the other six extend. */
 export const lightPalettes = {