pixelize-design-library 2.4.2-beta.66 → 2.4.2-beta.68

package/dist/Components/WizardDialog/wizardSteps.d.ts

@@ -1,24 +1,36 @@
 export type StepValidator = () => string[];
 /** Reducer state: current step, the furthest validly reached step, and the blocking messages. */
 export type WizardState = {
+    /** Zero-based index of the current step. */
     index: number;
     /** Furthest step the user has validly reached; stages beyond it stay locked. */
     furthest: number;
+    /** Messages blocking the current step; [] when none. */
     errors: string[];
 };
 /** Actions `wizardTransition` understands. */
-export type WizardAction = {
+export type WizardAction = 
+/** Validates the current step, then advances; failing keeps the step and stores its errors. */
+{
     type: "next";
-} | {
+}
+/** Steps back one, clearing errors. */
+ | {
     type: "back";
-} | {
+}
+/** Jumps to `index` if it is at or before `furthest`; otherwise ignored. */
+ | {
     type: "goto";
     index: number;
-} | {
+}
+/** Moves to `index` and shows `errors`, used when finishing finds an invalid step. */
+ | {
     type: "fail";
     index: number;
     errors: string[];
-} | {
+}
+/** Returns to the first step with nothing reached beyond it. */
+ | {
     type: "reset";
 };
 export declare const INITIAL_WIZARD_STATE: WizardState;

package/dist/Components/WorkspaceWindow/WorkspaceTrayPreview.d.ts

@@ -1,2 +1,3 @@
 import type { WorkspaceTrayPreviewProps } from "./WorkspaceWindowProps";
+/** Hover and focus preview card with open delay, close grace and Escape dismissal. */
 export default function WorkspaceTrayPreview({ children, preview, enabled, openDelayMs, closeDelayMs, placement, onOpenChange, width, testId, }: WorkspaceTrayPreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/WorkspaceWindow/WorkspaceTrayPreview.js

@@ -16,7 +16,7 @@ const PLACEMENT_STYLE = {
     "bottom-end": { top: "100%", right: 0, marginTop: "6px" },
     "bottom-start": { top: "100%", left: 0, marginTop: "6px" },
 };
-// Presentational, app-agnostic hover-preview (intent-safe: open delay, close grace, Escape dismisses).
+/** Hover and focus preview card with open delay, close grace and Escape dismissal. */
 function WorkspaceTrayPreview({ children, preview, enabled = true, openDelayMs = 350, closeDelayMs = 200, placement = "top-end", onOpenChange, width = "340px", testId = "workspace-tray-preview", }) {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const cardId = (0, react_1.useId)();

package/dist/Components/WorkspaceWindow/WorkspaceWindow.d.ts

@@ -1,3 +1,5 @@
 import type { WorkspaceTrayProps, WorkspaceWindowProps } from "./WorkspaceWindowProps";
+/** Floating Jira-style workspace window; headless, so the parent owns its `state`. */
 export default function WorkspaceWindow({ title, state, children, onMinimize, onClose, onOpenFullPage, onOverlayClick, headerActions, labels, finalFocusRef, testId, }: WorkspaceWindowProps): import("react/jsx-runtime").JSX.Element | null;
+/** Row of minimized-window pills, portalled above modals. */
 export declare function WorkspaceTray({ items, onRestore, onClose, testId, placement, offset, closeLabel, dirtyLabel, label, renderItem, }: WorkspaceTrayProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/Components/WorkspaceWindow/WorkspaceWindow.js

@@ -24,7 +24,7 @@ const WindowTitle = ({ testId, color, children }) => {
     }, [setHeaderMounted]);
     return ((0, jsx_runtime_1.jsx)(react_1.Text, { id: headerId, fontSize: "sm", fontWeight: 600, color: color, noOfLines: 1, "data-testid": `${testId}-title`, children: children }));
 };
-// Presentational floating "workspace window" (Jira-style dialog), headless — the parent owns window state.
+/** Floating Jira-style workspace window; headless, so the parent owns its `state`. */
 function WorkspaceWindow({ title, state, children, onMinimize, onClose, onOpenFullPage, onOverlayClick, headerActions, labels, finalFocusRef, testId = "workspace-window", }) {
     var _a, _b, _c;
     // Must run before the early return: a minimized render would otherwise skip the hook
@@ -44,6 +44,7 @@ function WorkspaceWindow({ title, state, children, onMinimize, onClose, onOpenFu
                 }, "data-testid": `${testId}-backdrop`, children: (0, jsx_runtime_1.jsxs)(react_1.Box, { bg: theme.colors.surfaceRaised, borderRadius: "xl", boxShadow: "2xl", overflow: "hidden", w: "100%", maxW: size.maxW, h: size.h, display: "flex", flexDirection: "column", "data-testid": testId, "data-window-state": state, children: [(0, jsx_runtime_1.jsxs)(react_1.Flex, { align: "center", justify: "space-between", px: 3, py: 2, borderBottomWidth: "1px", borderColor: (0, surfaceRaised_1.raisedRule)(theme.colors), bg: (0, planeStep_1.bandOn)(theme.colors.background[100], theme.colors.surfaceRaised), flexShrink: 0, children: [(0, jsx_runtime_1.jsx)(WindowTitle, { testId: testId, color: theme.colors.text[700], children: title }), (0, jsx_runtime_1.jsxs)(react_1.HStack, { spacing: 1, children: [headerActions, onOpenFullPage ? ((0, jsx_runtime_1.jsx)(react_1.IconButton, { "aria-label": (_a = labels === null || labels === void 0 ? void 0 : labels.openFullPage) !== null && _a !== void 0 ? _a : "Open full page", size: "xs", variant: "ghost", icon: (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { size: 14 }), onClick: onOpenFullPage, "data-testid": `${testId}-fullpage` })) : null, onMinimize ? ((0, jsx_runtime_1.jsx)(react_1.IconButton, { "aria-label": (_b = labels === null || labels === void 0 ? void 0 : labels.minimize) !== null && _b !== void 0 ? _b : "Minimize", size: "xs", variant: "ghost", icon: (0, jsx_runtime_1.jsx)(lucide_react_1.Minus, { size: 15 }), onClick: onMinimize, "data-testid": `${testId}-minimize` })) : null, onClose ? ((0, jsx_runtime_1.jsx)(react_1.IconButton, { "aria-label": (_c = labels === null || labels === void 0 ? void 0 : labels.close) !== null && _c !== void 0 ? _c : "Close", size: "xs", variant: "ghost", colorScheme: "red", icon: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { size: 15 }), onClick: onClose, "data-testid": `${testId}-close` })) : null] })] }), (0, jsx_runtime_1.jsx)(react_1.Box, { flex: "1", overflow: "auto", px: { base: 3, md: 5 }, py: 4, children: children })] }) })] }));
 }
 const cssLength = (value) => (typeof value === "number" ? `${value}px` : value);
+/** Row of minimized-window pills, portalled above modals. */
 // Portalled above modal overlays; aria-live keeps Chakra's modal aria-hidden off it, data-no-focus-lock keeps the focus trap off it.
 function WorkspaceTray({ items, onRestore, onClose, testId = "workspace-tray", placement = "bottom-end", offset, closeLabel, dirtyLabel = "Unsaved changes", label = "Minimized windows", renderItem, }) {
     var _a, _b;

package/dist/Components/WorkspaceWindow/WorkspaceWindowProps.d.ts

@@ -23,11 +23,13 @@ export interface WorkspaceWindowProps {
     state: WorkspaceWindowState;
     /** Window body. */
     children: ReactNode;
+    /** Adds the Minimize button to the control bar; omitted hides it. The parent sets `state` to "minimized" itself. */
     onMinimize?: () => void;
     /** @deprecated Never called; no maximize/restore control is rendered. */
     onMedium?: () => void;
     /** @deprecated Never called; no maximize/restore control is rendered. */
     onMaximize?: () => void;
+    /** Adds the Close button to the control bar and is its only trigger: Esc and backdrop clicks never close the window. */
     onClose?: () => void;
     /** Optional "pop out to full page" affordance; hidden when omitted. */
     onOpenFullPage?: () => void;
@@ -52,7 +54,9 @@ export interface WorkspaceWindowProps {
 }
 /** One minimized window in the tray; id is passed back to onRestore/onClose so callers can target the right window. */
 export interface WorkspaceTrayItem {
+    /** Identifier handed back to `onRestore` and `onClose`. */
     id: string;
+    /** Main text of the pill. */
     title: ReactNode;
     /** Shows an unsaved-changes dot on the built-in pill; named for screen readers by the tray's `dirtyLabel`. */
     isDirty?: boolean;
@@ -63,14 +67,19 @@ export interface WorkspaceTrayItem {
 export interface WorkspaceTrayProps {
     /** Minimized items rendered as restore pills along the bottom. */
     items: WorkspaceTrayItem[];
+    /** Called with the item id when its pill is clicked to bring the window back. */
     onRestore?: (id: string) => void;
+    /** Called with the item id from the pill's close button; omitted removes that button. */
     onClose?: (id: string) => void;
+    /** data-testid for the tray; pills, restore, dirty dot and close buttons derive suffixed ids from it. Default "workspace-tray". */
     testId?: string;
     /** Which bottom corner the tray sits in. Default "bottom-end". Portalled above modals but outside their focus trap: a pointer restores a pill while a modal is open, Tab does not reach it. */
     placement?: "bottom-end" | "bottom-start";
     /** Distance from the viewport edges, to clear a sticky bar. Numbers are px, strings any CSS length. Default 1rem each. */
     offset?: {
+        /** Gap from the side edge. */
         x?: number | string;
+        /** Gap from the bottom edge. */
         y?: number | string;
     };
     /** Accessible name for each pill's close button. Default "Close"; pass one that names the item for non-English or per-window labels. */
@@ -81,7 +90,9 @@ export interface WorkspaceTrayProps {
     label?: string;
     /** Replaces one item's pill inside the same tray; gets the item, bound restore/close and `pill`, the built-in pill (dot, subtitle, close button) to return as is or wrap, e.g. in WorkspaceTrayPreview. */
     renderItem?: (item: WorkspaceTrayItem, api: {
+        /** Calls `onRestore` with this item's id. */
         restore: () => void;
+        /** Calls `onClose` with this item's id. */
         close: () => void;
     }, pill: ReactNode) => ReactNode;
 }
@@ -100,6 +111,7 @@ export interface WorkspaceTrayPreviewProps {
      * on the one focusable trigger so assistive tech hears the card.
      */
     children: ReactNode | ((api: {
+        /** Accessibility attributes to spread on the one focusable trigger. */
         triggerProps: WorkspaceTrayPreviewTriggerProps;
     }) => ReactNode);
     /**
@@ -109,6 +121,7 @@ export interface WorkspaceTrayPreviewProps {
      * the preview can dismiss it.
      */
     preview: ReactNode | ((api: {
+        /** Closes the card immediately, e.g. after an action inside it. */
         close: () => void;
     }) => ReactNode);
     /** Whether the preview is enabled at all (e.g. disable on touch devices). */

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

@@ -22,7 +22,7 @@ export declare const LIGHT_CANVAS_STEP = 1.09;
 export declare const finalizeLightPalette: (source: BrandPaletteSource) => PaletteProps;
 export { lavender, meadow, radiant, skyline, slate, emerald, rosewood, storefront, zinc };
 export { lavenderDark, meadowDark, radiantDark, skylineDark, slateDark, emeraldDark, rosewoodDark, storefrontDark, zincDark, };
-/** Light palette per brand, derived on first read. `lavender` is the base the other six extend. */
+/** Light palette per brand, derived on first read. `lavender` is the base the other eight extend. */
 export declare const lightPalettes: Record<ThemeName, PaletteProps>;
 export declare const darkPalettes: Record<ThemeName, PaletteProps>;
 export declare const palettes: Record<ThemeName, Record<ResolvedColorMode, PaletteProps>>;

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

@@ -84,7 +84,7 @@ exports.finalizeLightPalette = finalizeLightPalette;
 // NOTE: withFocusRing is outermost — it must see primary and surfaces together, after every earlier step.
 const resolveRungs = (palette) => (0, focusRing_1.withFocusRing)((0, surfaceRungs_1.withSurfaceRungs)((0, surfaceRaised_1.withSurfaceRaised)((0, resolvedRungs_1.withTableHoverRung)((0, resolvedRungs_1.withPlaceholderRung)((0, outlineRung_1.withOutlineRung)(palette))))));
 const lightBrand = (source) => (0, lazy_1.lazyPalette)(source, () => resolveRungs((0, exports.finalizeLightPalette)(source)));
-/** Light palette per brand, derived on first read. `lavender` is the base the other six extend. */
+/** Light palette per brand, derived on first read. `lavender` is the base the other eight extend. */
 exports.lightPalettes = {
     lavender: lightBrand(palette_light_1.default),
     meadow: lightBrand(palette_light_2.default),

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

@@ -5,3 +5,9 @@ export interface RowStateBackgrounds {
     selectedActive: string;
 }
 export declare const listRowBackgrounds: (colors: PaletteProps) => RowStateBackgrounds;
+export declare const SELECTED_ROW_STEP = 1.28;
+export declare const DISTINCT_ROW_STEP = 1.1;
+export interface SelectRowBackgrounds extends RowStateBackgrounds {
+    keyboardRing: string;
+}
+export declare const selectRowBackgrounds: (colors: PaletteProps) => SelectRowBackgrounds;

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listRowBackgrounds = void 0;
+exports.selectRowBackgrounds = exports.DISTINCT_ROW_STEP = exports.SELECTED_ROW_STEP = exports.listRowBackgrounds = void 0;
+const accentText_1 = require("./accentText");
+const color_1 = require("./color");
 const outlineRung_1 = require("./outlineRung");
 const listRowBackgrounds = (colors) => {
     // Raw tertiary reaches 1.29:1 and reads as pressed; dark aliases it to the panel at 1.025:1.
@@ -12,3 +14,19 @@ const listRowBackgrounds = (colors) => {
     };
 };
 exports.listRowBackgrounds = listRowBackgrounds;
+exports.SELECTED_ROW_STEP = 1.28;
+exports.DISTINCT_ROW_STEP = 1.1;
+// NOTE: light steps deeper in the hover tint's own hue; dark uses neutral greys. Both derive direction from the panel.
+const selectRowBackgrounds = (colors) => {
+    const panel = colors.surfaceRaised;
+    const { active: hoverTint } = (0, exports.listRowBackgrounds)(colors);
+    const isDark = (0, accentText_1.isDarkCanvas)(panel);
+    const active = isDark ? (0, outlineRung_1.neutralStep)(panel, outlineRung_1.MIN_PERCEPTIBLE_STEP) : hoverTint;
+    const selectedStep = Math.max(exports.SELECTED_ROW_STEP, (0, color_1.contrastRatio)(active, panel) * exports.DISTINCT_ROW_STEP);
+    const selected = isDark ? (0, outlineRung_1.neutralStep)(panel, selectedStep) : (0, outlineRung_1.tintStep)(hoverTint, panel, selectedStep);
+    const selectedActive = isDark
+        ? (0, outlineRung_1.neutralStep)(selected, outlineRung_1.STACKED_STATE_STEP)
+        : (0, outlineRung_1.tintStep)(selected, selected, outlineRung_1.STACKED_STATE_STEP);
+    return { active, selected, selectedActive, keyboardRing: (0, outlineRung_1.neutralStep)(selectedActive, outlineRung_1.AA_NON_TEXT) };
+};
+exports.selectRowBackgrounds = selectRowBackgrounds;

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

@@ -1,2 +1,3 @@
 export type ScrollShadowStyle = Record<string, unknown>;
 export declare function scrollShadowStyles(surface: string): ScrollShadowStyle;
+export declare function scrollShadowStylesVertical(surface: string): ScrollShadowStyle;

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

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scrollShadowStyles = scrollShadowStyles;
+exports.scrollShadowStylesVertical = scrollShadowStylesVertical;
+const accentText_1 = require("./accentText");
 const EDGE = "24px";
 const TINT = "rgba(0, 0, 0, 0.08)";
+const TINT_ON_DARK = "rgba(0, 0, 0, 0.32)";
+const VERTICAL_SHADOW = "8px";
 // CSS-only overflow hint via background-attachment local vs scroll — no listener, no extra node.
 function scrollShadowStyles(surface) {
     return {
@@ -14,3 +18,15 @@ function scrollShadowStyles(surface) {
         backgroundAttachment: "local, local, scroll, scroll",
     };
 }
+// NOTE: dark panels swallow an 8% black edge, so the vertical hint steps up on a dark surface.
+function scrollShadowStylesVertical(surface) {
+    const tint = (0, accentText_1.isDarkCanvas)(surface) ? TINT_ON_DARK : TINT;
+    return {
+        backgroundColor: surface,
+        backgroundImage: `linear-gradient(${surface}, ${surface}), linear-gradient(${surface}, ${surface}), linear-gradient(${tint}, transparent), linear-gradient(transparent, ${tint})`,
+        backgroundRepeat: "no-repeat",
+        backgroundSize: `100% ${EDGE}, 100% ${EDGE}, 100% ${VERTICAL_SHADOW}, 100% ${VERTICAL_SHADOW}`,
+        backgroundPosition: "0 0, 0 100%, 0 0, 0 100%",
+        backgroundAttachment: "local, local, scroll, scroll",
+    };
+}

package/dist/esm/Components/AppSwitcher/AppSwitcher.js

@@ -41,6 +41,7 @@ const validate = (apps) => {
 };
 // Flip back to true to restore `searchThreshold` opening the field on its own.
 const SEARCH_OPENS_BY_COUNT = false;
+/** Top-bar grid button that opens a panel of suite apps to jump between, with optional search and keyboard shortcut. */
 const AppSwitcher = ({ apps, currentAppId, onSelect, onOpenChange, isSearchable, searchThreshold = 8, shortcut = null, showShortcutHint = true, hideWhenAlone = true, emptyMessage = "No app matches that name.", footer, ariaLabel = "Switch app", panelWidth, maxHeight = "24rem", isLoading = false, }) => {
     const theme = useCustomTheme();
     const { isOpen, onOpen, onClose } = useDisclosure();

package/dist/esm/Components/AppearanceSettings/AppearanceSettings.js

@@ -13,6 +13,7 @@ const FieldLabel = ({ children }) => {
     return (_jsx(Text, { fontSize: "sm", fontWeight: 500, color: colors.textMuted, mb: 2, children: children }));
 };
 const brandSwatch = (name, colors) => (_jsx(Box, { w: "14px", h: "14px", borderRadius: "full", bg: lightPalettes[name].primary[500], border: "1px solid", borderColor: ruleInk(colors.boxborder[200], [colors.backgroundColor.light, colors.backgroundColor.tertiary], CHROME_RULE) }));
+/** Settings panel with brand, light/dark mode and root font-size pickers; each section can be hidden. */
 export const AppearanceSettings = ({ brand, fontSize, onBrandChange, onFontSizeChange, showBrand = true, showColorMode = true, showFontSize = true, size = "sm", labels, }) => {
     var _a, _b, _c;
     const { colors } = useCustomTheme();

package/dist/esm/Components/AudioRecorder/AudioRecorder.js

@@ -33,6 +33,7 @@ export const recordingFileName = (mime, now) => {
     return { type, name: `recording-${now}.${(_a = EXTENSIONS[type]) !== null && _a !== void 0 ? _a : (((_b = type.split("/")[1]) === null || _b === void 0 ? void 0 : _b.replace(/^x-/, "")) || "webm")}` };
 };
 const isSupported = () => { var _a; return typeof navigator !== "undefined" && !!((_a = navigator.mediaDevices) === null || _a === void 0 ? void 0 : _a.getUserMedia) && typeof MediaRecorder !== "undefined"; };
+/** Microphone recorder: a toggle button and timer that hands a `File` to `onRecorded` on stop. */
 const AudioRecorder = ({ onRecorded, maxDurationSec, isDisabled = false, labels }) => {
     const { colors } = useCustomTheme();
     const text = { ...DEFAULT_LABELS, ...labels };

package/dist/esm/Components/Avatar/AvatarGroup.js

@@ -8,6 +8,7 @@ const summarize = (names, overflow) => {
         return names.join(", ");
     return `${names.join(", ")} and ${overflow} more`;
 };
+/** Overlapping avatar stack; people past `max` collapse into a "+N" chip. */
 const AvatarGroup = ({ people, max = 4, size = "md", ariaLabel, "data-testid": testId }) => {
     const { colors } = useCustomTheme();
     const shown = people.slice(0, max);

package/dist/esm/Components/BulkSelectionBar/BulkSelectionBar.js

@@ -16,6 +16,7 @@ const SCHEME_BY_TONE = {
     danger: "red",
 };
 const TOUCH_SX = { "@media (pointer: coarse)": { minHeight: "44px", minWidth: "44px" } };
+/** Action bar for table row selection: count, shared facts, bulk action buttons and a clear button; renders nothing at zero. */
 const BulkSelectionBar = ({ selectedCount, facts, actions, onClearSelection, clearLabel = "Clear selection", countLabel, placement = "sticky", "aria-label": ariaLabel = "Selection actions", "data-testid": testId = "bulk-selection-bar", }) => {
     const { colors } = useCustomTheme();
     const isActive = selectedCount > 0;

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

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef, memo } from "react";
 import { Button as ChakraButton } from "@chakra-ui/react";
+/** Themed button with label or children, left/right icons and a loading state that keeps its width. */
 const Button = forwardRef(function Button({ label, children, onClick, opacity, variant = "solid", leftIcon, rightIcon, size, isDisabled = false, isLoading = false, loadingText, type, width, w, sx, colorScheme, border, borderRadius, onMouseEnter, onMouseLeave, ...aria }, ref) {
     const isIconOnly = !children && !label && !!(leftIcon || rightIcon);
     return (_jsx(ChakraButton, { ...aria, type: type, onClick: onClick, width: width || w || "fit-content", variant: variant, size: size, isLoading: isLoading, isDisabled: isDisabled, loadingText: loadingText, leftIcon: leftIcon, rightIcon: rightIcon, iconSpacing: isIconOnly ? 0 : undefined, px: isIconOnly ? 0 : undefined, ref: ref, colorScheme: colorScheme, sx: sx, opacity: opacity, border: border, borderRadius: borderRadius, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, children: children !== null && children !== void 0 ? children : label }));

package/dist/esm/Components/ButtonGroupIcon/ButtonGroupIcon.js

@@ -7,6 +7,7 @@ import { hexToRgb } from "../../Theme/tokens/builders/color.js";
 import { rafThrottle } from "../../Utils/rafThrottle.js";
 import { transitionFor } from "../../Theme/tokens/primitives/motion.js";
 const BACKGROUND_TRANSITION = transitionFor(["background"]);
+/** Attached left icon, text button and right icon or dropdown trigger; see ButtonGroupIconProps. */
 export default function ButtonGroupIcon({ leftIcon, rightIcon, onLeftIconClick, onRightIconClick, buttonText, onButtonClick, onButtongroupClick, size, variant, color, buttonGroupStyle, buttonGroupLeftIconStyle, buttonGroupRightIconStyle, buttonStyle, onBlurLeftIcon, onBlurRightIcon, dropdownOptions, // New prop for dropdown options
 onDropdownOptionClick, // New prop to handle option clicks
 rightIconDropdown, menulistStyle, menuItemStyle, isLoading, divider = true, leftIconLoading, RightIconLoading, }) {

package/dist/esm/Components/CalendarGrid/CalendarGrid.js

@@ -73,6 +73,7 @@ const EventChip = ({ event, colors, surface, onEventClick, segment }) => {
     };
     return event.href ? (_jsx(Box, { as: "a", href: event.href, ...common, children: event.label })) : (_jsx(Box, { as: "button", type: "button", ...common, children: event.label }));
 };
+/** Controlled month, week or day grid that places date-granularity events as chips and spanning bars, with a toolbar and arrow-key navigation. */
 const CalendarGrid = ({ view, date, events, onViewChange, onDateChange, onEventClick, renderDayCell, weekStartsOn = 0, locale, isLoading = false, labels, }) => {
     const { colors } = useCustomTheme();
     const text = { ...DEFAULT_LABELS, ...labels };

package/dist/esm/Components/Card/PaymentCard/PaymentCard.js

@@ -58,6 +58,7 @@ const getCardStyles = (isActive, isNextUpgrade, popular, theme) => {
         colorScheme: "primary",
     });
 };
+/** Subscription plan card with price, feature list and a call-to-action; badge and accent follow active, upgrade and popular state. */
 const PaymentCard = ({ plan, isActive = false, isNextUpgrade = false, billingCycle, onSelect, onHover, buttonLoading, isLoading = false, isRenewal = false, }) => {
     const theme = useCustomTheme();
     const { badgeText, badgeColor, buttonColor, buttonColor50, onButtonColor, iconInk, colorScheme } = getCardStyles(isActive, isNextUpgrade, !!plan.popular, theme);

package/dist/esm/Components/ChoiceCard/ChoiceCard.js

@@ -3,6 +3,7 @@ import { useId } from "react";
 import { Box, Flex, Text } from "@chakra-ui/react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { RadioIndicator, selectableSurface, useSelectable } from "../CheckoutKit/selectable.js";
+/** Selectable radio card with a label, optional description and icon; must sit inside a `ChoiceCardGroup`. */
 const ChoiceCard = ({ value, label, description, icon, disabled: disabledProp = false, isDisabled = false, "data-testid": testId }) => {
     const disabled = disabledProp || isDisabled;
     const { colors } = useCustomTheme();

package/dist/esm/Components/ChoiceCard/ChoiceCardGroup.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { SelectableGroup } from "../CheckoutKit/selectable.js";
+/** Radiogroup that lays out `ChoiceCard`s in one or more columns and manages the single selection. */
 const ChoiceCardGroup = (props) => _jsx(SelectableGroup, { ...props });
 export default ChoiceCardGroup;

package/dist/esm/Components/ConfirmDialog/ConfirmDialog.js

@@ -7,6 +7,7 @@ import { raisedRule } from "../../Theme/tokens/builders/surfaceRaised.js";
 import { resolveSoftTone } from "../../Theme/tokens/builders/tone.js";
 import Button from "../Button/Button.js";
 import TextInput from "../Input/TextInput.js";
+/** Cancel/Confirm modal for destructive prompts; focus starts on Cancel and Confirm never closes the dialog itself. */
 const ConfirmDialog = ({ isOpen, onClose, onConfirm, title, children, icon, iconBg, iconColor, entityName, entityKind, dependents, consequence, alternative, isConfirmDisabled: isConfirmHeld = false, tone = "destructive", cancelLabel = "Cancel", confirmLabel = "Confirm", confirmIcon, isConfirmLoading = false, disableCancelWhilePending = true, confirmationText, confirmationLabel, bodyLayout = "flush", bodySpacing = 4, actionsPt = 0, focusCancelOnOpen = true, isCentered = true, closeOnEsc, closeOnOverlayClick, }) => {
     const { colors } = useCustomTheme();
     const cancelRef = useRef(null);

package/dist/esm/Components/CustomModulesTable/CustomModulesTable.js

@@ -26,6 +26,7 @@ const DEFAULT_LABELS = {
     confirmDeletion: "Confirm Deletion",
     deleteConfirmPrefix: "Are you sure you want to delete",
 };
+/** Card with a two-column module list (name, owner) and per-row Edit and Delete dialogs; loading shows skeleton bars, empty shows an empty state. */
 const CustomModulesTable = ({ modules, isLoading = false, isUpdating = false, isDeleting = false, onUpdateModule, onDeleteModule, labels: labelOverrides, }) => {
     var _a;
     const { colors } = useCustomTheme();

package/dist/esm/Components/CustomModulesTable/DeleteModuleModal.js

@@ -4,6 +4,7 @@ import { Trash2 } from "lucide-react";
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { accentTextOnCanvas } from "../../Theme/tokens/builders/accentText.js";
 import ConfirmDialog from "../ConfirmDialog/ConfirmDialog.js";
+/** Confirmation dialog for deleting a module; used by CustomModulesTable. */
 const DeleteModuleModal = ({ isOpen, onClose, moduleName, isLoading, onConfirm, labels, }) => {
     const { colors } = useCustomTheme();
     return (_jsx(ConfirmDialog, { isOpen: isOpen, onClose: onClose, onConfirm: onConfirm, title: labels.confirmDeletion, iconBg: colors.semantic.error[50], iconColor: accentTextOnCanvas(colors.semantic.error, colors.semantic.error[50]), cancelLabel: labels.cancel, confirmLabel: labels.delete, confirmIcon: _jsx(Trash2, { size: 15 }), isConfirmLoading: isLoading, disableCancelWhilePending: false, focusCancelOnOpen: false, children: _jsxs(Text, { color: colors.textMuted, fontSize: "sm", mb: 5, children: [labels.deleteConfirmPrefix, " ", _jsx(Text, { as: "span", fontWeight: 600, color: colors.text[800], children: moduleName }), "?"] }) }));

package/dist/esm/Components/CustomModulesTable/EditModuleModal.js

@@ -4,6 +4,7 @@ import { Modal, ModalOverlay, ModalContent, ModalHeader, ModalCloseButton, Modal
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { raisedRule } from "../../Theme/tokens/builders/surfaceRaised.js";
 import Button from "../Button/Button.js";
+/** Dialog with one text field to rename a module; used by CustomModulesTable. */
 const EditModuleModal = ({ isOpen, onClose, initialName, isLoading, onSubmit, labels, }) => {
     const { colors } = useCustomTheme();
     const [name, setName] = useState(initialName);

package/dist/esm/Components/FormDrawer/FormDrawer.js

@@ -12,6 +12,7 @@ const DEFAULT_LABELS = {
     discard: "Discard",
     keepEditing: "Keep editing",
 };
+/** Sectioned create/edit form in a Drawer with error summary, sticky footer and discard-changes confirm. */
 export default function FormDrawer({ isOpen, onClose, title, description, sections, errors = [], isDirty, onSubmit, isSubmitting = false, isSubmitDisabled = false, submitLabel = "Save", cancelLabel = "Cancel", secondaryAction, size = "md", labels, "data-testid": testId = "form-drawer", }) {
     const { colors } = useCustomTheme();
     const uid = useId();

package/dist/esm/Components/FormField/FormField.js

@@ -10,6 +10,7 @@ const joinIds = (...ids) => [...new Set(ids.flatMap((value) => { var _a; return
 const asWirableElement = (children) => typeof children !== "function" && isValidElement(children) && children.type !== Fragment
     ? children
     : undefined;
+/** Wires a label, required marker, helper and error text to one control through ids and aria attributes. */
 const FormField = forwardRef(function FormField({ label, id, isRequired = false, error = false, errorMessage, helperText, layout = "vertical", labelWidth = "12rem", children, ...rest }, ref) {
     var _a;
     const { colors } = useCustomTheme();

package/dist/esm/Components/Header/Header.js

@@ -18,6 +18,7 @@ export const pickActiveAccent = (primary, canvas) => {
     const found = order.find((rung) => contrastRatio(primary[rung], canvas) >= ACTIVE_ACCENT_TARGET);
     return primary[found !== null && found !== void 0 ? found : order[order.length - 1]];
 };
+/** Sticky top bar with logo, page links, hover dropdowns and a collapsible mobile menu; colours default to the sidebar tokens. */
 const Header = ({ logo, menuItems, rightSlot, active, colors, boxShadow, onMobileMenuClose }) => {
     var _a, _b, _c, _d, _e;
     const { isOpen, onOpen, onClose } = useDisclosure();

package/dist/esm/Components/Header/HeaderActions.js

@@ -8,6 +8,7 @@ import { AA_NON_TEXT, liftToContrast } from "../../Theme/tokens/builders/outline
 import Select from "../Select/Select.js";
 import VerticalDivider from "../Divider/Divider.js";
 import { surfaceFocusRing } from "../Common/surfaceFocusRing.js";
+/** Row of optional header controls (select, edit, create) separated by dividers; each renders only when its flag is set. */
 const HeaderActions = ({ select, edit, create, surface, }) => {
     var _a, _b, _c;
     const { colors } = useCustomTheme();

package/dist/esm/Components/Header/components/desktopMenu.js

@@ -5,6 +5,7 @@ import { useCustomTheme } from "../../../Theme/useCustomTheme.js";
 import { onFilled } from "../../../Theme/tokens/builders/accentText.js";
 import { resolveSoftTone } from "../../../Theme/tokens/builders/tone.js";
 import { scaleFor } from "../../../Theme/chakra/paletteFromTheme.js";
+/** Desktop nav row of Header: ghost buttons with hover dropdowns for items that have children. */
 const DesktopMenu = ({ menuItems, rightSlot, setHoveredMenu, isActive, activeBg, hoveredMenu, hoverBg, color, hoverTextColor, surface, }) => {
     const { colors } = useCustomTheme();
     const badgeTone = (scheme) => resolveSoftTone(colors, scaleFor(colors, scheme !== null && scheme !== void 0 ? scheme : "blue"), surface);

package/dist/esm/Components/Header/components/mobileMenu.js

@@ -6,6 +6,7 @@ import { useCustomTheme } from "../../../Theme/useCustomTheme.js";
 import { onFilled } from "../../../Theme/tokens/builders/accentText.js";
 import { resolveSoftTone } from "../../../Theme/tokens/builders/tone.js";
 import { scaleFor } from "../../../Theme/chakra/paletteFromTheme.js";
+/** Collapsible mobile nav panel of Header; items with children toggle an inline submenu. */
 const MobileMenu = ({ menuItems, isOpen, isActive, hoverBg, activeBg, color, surface, onClose, }) => {
     const { colors } = useCustomTheme();
     const badgeTone = (scheme) => resolveSoftTone(colors, scaleFor(colors, scheme !== null && scheme !== void 0 ? scheme : "blue"), surface);

package/dist/esm/Components/KanbanBoard/KanbanActions/KanbanActions.js

@@ -5,7 +5,7 @@ import { CirclePlus, SquarePen } from "lucide-react";
 import VerticalDivider from "../../Divider/Divider.js";
 import { useCustomTheme } from "../../../Theme/useCustomTheme.js";
 import Button from "../../Button/Button.js";
-/** Standalone filter+Edit+Create action bar; NOT rendered by KanbanBoard (which uses HeaderActions instead) and not exported from the package. */
+/** Standalone filter+Edit+Create bar, exported from the package; KanbanBoard itself uses HeaderActions. */
 const KanbanActions = ({ options, onSelectChange, onEdit, onCreate, }) => {
     const { colors } = useCustomTheme();
     return (_jsxs(Box, { display: "flex", alignItems: "center", gap: "0.625rem", children: [_jsx(Select, { native: false, options: options, placeholder: "Filter by Status", width: "12.5rem", onChange: (option) => onSelectChange && onSelectChange(option) }), _jsxs(Box, { display: "flex", alignItems: "center", gap: "0.5rem", children: [_jsx(Button, { size: "sm", variant: "ghost", leftIcon: _jsx(SquarePen, { size: 20, color: colors.text[500] }), onClick: () => onEdit === null || onEdit === void 0 ? void 0 : onEdit(), children: "Edit Layout" }), _jsx(VerticalDivider, {}), _jsx(Button, { size: "sm", variant: "solid", leftIcon: _jsx(CirclePlus, { size: 20 }), onClick: () => onCreate === null || onCreate === void 0 ? void 0 : onCreate(), children: "Create New" })] })] }));

package/dist/esm/Components/Kbd/Kbd.js

@@ -18,6 +18,7 @@ const Kbd = ({ children, size = "sm", "data-testid": testId }) => {
     const { colors } = useCustomTheme();
     return (_jsx(Box, { as: "kbd", "data-testid": testId, display: "inline-flex", alignItems: "center", justifyContent: "center", minW: HEIGHT[size], h: HEIGHT[size], px: 1.5, fontFamily: "inherit", fontSize: "xs-minus", fontWeight: 600, lineHeight: 1, whiteSpace: "nowrap", borderWidth: "1px", borderColor: colors.boxborder[200], borderRadius: "base", bg: colors.backgroundColor.subtle, color: colors.textMuted, children: children }));
 };
+/** Renders a chord such as `mod+k` as one `Kbd` per key, announced as a single spoken label. */
 export const KbdShortcut = ({ shortcut, size, isApple, "data-testid": testId }) => {
     const parts = shortcut.split("+").map((p) => p.trim()).filter(Boolean);
     const apple = isApple !== null && isApple !== void 0 ? isApple : detectApple();

package/dist/esm/Components/LauncherTrigger/LauncherTrigger.js

@@ -28,6 +28,7 @@ export const keyShortcutsFor = (shortcut) => {
     const chords = Array.from({ length: variants }, (_, v) => options.map((o) => o[Math.min(v, o.length - 1)]).join("+"));
     return Array.from(new Set(chords)).join(" ");
 };
+/** Chip or icon button that opens an app-owned launcher; shows the shortcut hint but binds no key. */
 const LauncherTrigger = ({ onClick, isOpen, label = "Menu", shortcut = "mod+k", icon: Icon = Compass, display = "chip", "aria-label": ariaLabel, "data-testid": testId, }) => {
     const { colors } = useCustomTheme();
     const showHint = useMatchMedia(MD_QUERY, true);

package/dist/esm/Components/LimitReachedModal/LimitReachedModal.js

@@ -14,6 +14,7 @@ const KIND_ICON = {
     projects: Crown,
     tickets: Crown,
 };
+/** Controlled plan-limit modal: kind-specific title and message, optional usage line and feature list, upgrade CTA only for billing managers. */
 const LimitReachedModal = ({ isOpen, onClose, kind, limit = null, used = null, canManageBilling, onUpgrade, title, message, features, }) => {
     const { colors } = useCustomTheme();
     const copy = resolveLimitCopy(kind, canManageBilling);

package/dist/esm/Components/MediaViewer/components/MediaAudioPlayer.js

@@ -14,6 +14,7 @@ import { transitionFor } from "../../../Theme/tokens/primitives/motion.js";
 const VOLUME_WIDTH_TRANSITION = transitionFor(["width"], "base", "out");
 const ARROW_SEEK_SECONDS = 5;
 const ARROW_VOLUME_STEP = 0.1;
+/** Audio stage of MediaViewer: play/pause, seek, volume and playback-speed controls with J / L skip keys. */
 const MediaAudioPlayer = ({ item, label, onTimeChange, labels: labelOverrides }) => {
     const labels = { ...defaultMediaAudioPlayerLabels, ...labelOverrides };
     const chrome = useViewerChrome();

package/dist/esm/Components/MediaViewer/components/MediaDocumentStage.js

@@ -77,6 +77,7 @@ function TextStage({ itemKey, url, blob, label, labels }) {
     }
     return (_jsx(Box, { position: "absolute", inset: 0, overflow: "auto", px: { base: 3, md: 8 }, py: 4, "data-testid": "media-text", children: _jsx(Text, { as: "pre", fontFamily: "mono", fontSize: "sm", whiteSpace: "pre-wrap", wordBreak: "break-word", color: chrome.ink, children: state.text }) }));
 }
+/** Document stage of MediaViewer: previews PDF, DOCX and text files inline, other kinds get a download panel; loading and error states come from `resolveDocument`. */
 export const MediaDocumentStage = ({ item, label, resolveDocument, labels: labelOverrides, }) => {
     const labels = { ...defaultMediaDocumentStageLabels, ...labelOverrides };
     const chrome = useViewerChrome();

package/dist/esm/Components/MediaViewer/components/MediaImageViewer.js

@@ -13,6 +13,7 @@ import { transitionFor } from "../../../Theme/tokens/primitives/motion.js";
 const TRANSFORM_OUT_TRANSITION = transitionFor(["transform"], "fast", "out");
 const ORIGIN = { x: 0, y: 0 };
 const transformFor = (pan, zoom, rotation) => `translate(${pan.x}px, ${pan.y}px) scale(${zoom / 100}) rotate(${rotation}deg)`;
+/** Image stage of MediaViewer with zoom, drag-to-pan, rotation and keyboard shortcuts. */
 const MediaImageViewer = ({ item, label, onZoomChange, onNaturalSize, labels: labelOverrides, }) => {
     const labels = { ...defaultMediaImageViewerLabels, ...labelOverrides };
     const chrome = useViewerChrome();

package/dist/esm/Components/MediaViewer/components/MediaVideoPlayer.js

@@ -24,6 +24,7 @@ const ARROW_VOLUME_STEP = 0.1;
 const spin = keyframes `from { transform: rotate(0deg); } to { transform: rotate(360deg); }`;
 const rippleFade = keyframes `0% { opacity: 0.9; } 100% { opacity: 0; }`;
 const seekIcon = (icon) => (_jsxs(Flex, { as: "span", align: "center", gap: "2px", "aria-hidden": true, children: [icon, _jsx(Text, { as: "span", fontSize: "xs", fontWeight: 600, children: SEEK_STEP_SECONDS })] }));
+/** Video stage of MediaViewer: transport, seek, volume, speed and fullscreen controls with keyboard shortcuts and double-tap skip. */
 const MediaVideoPlayer = ({ item, label, onTimeChange, onPrevious, onNext, labels: labelOverrides, }) => {
     const labels = { ...defaultMediaVideoPlayerLabels, ...labelOverrides };
     const chrome = useViewerChrome();

package/dist/esm/Components/MediaViewer/mediaItems.js

@@ -1,7 +1,12 @@
+/** Lowest image zoom, in percent. */
 export const MIN_ZOOM = 25;
+/** Highest image zoom, in percent. */
 export const MAX_ZOOM = 400;
+/** Percent added or removed by one zoom-in or zoom-out press. */
 export const ZOOM_STEP = 25;
+/** Rates offered in the playback-speed menu. */
 export const PLAYBACK_SPEEDS = [0.5, 0.75, 1, 1.25, 1.5, 2];
+/** Seconds skipped by the rewind and forward buttons and their J / L keys. */
 export const SEEK_STEP_SECONDS = 10;
 const ABSOLUTE_URL_RE = /^(blob:|data:|https?:)/;
 /** Passes an already-absolute url through untouched; only a bare stored path goes through resolveUrl. */

package/dist/esm/Components/Modal/Modal.js

@@ -3,12 +3,15 @@ import { Modal as ChakraModal, ModalOverlay, ModalContent, ModalHeader as Chakra
 import { useCustomTheme } from "../../Theme/useCustomTheme.js";
 import { warnDroppedSlotChildren } from "./warnDroppedSlotChildren.js";
 import { findSlot } from "../Common/findSlot.js";
+/** Header slot of `Modal`; its style props are spread onto the rendered header. */
 export const ModalHeader = ({ children }) => {
     return _jsx(_Fragment, { children: children });
 };
+/** Body slot of `Modal`; its style props are spread onto the rendered body. */
 export const ModalBody = ({ children }) => {
     return _jsx(_Fragment, { children: children });
 };
+/** Footer slot of `Modal`; its style props are spread onto the rendered footer. */
 export const ModalFooter = ({ children }) => {
     return _jsx(_Fragment, { children: children });
 };

package/dist/esm/Components/MultiSelect/MultiSelect.js

@@ -19,6 +19,7 @@ const generateUniqueId = (() => {
         return `${Date.now()}-${counter}`;
     };
 })();
+/** Email chip input: typed addresses are validated and committed on Enter, shown as removable chips. */
 export default function MultiSelect({ value, onValueChange, width = "100%", label = "label", isRequired = true, isInformation = false, informationMessage = "", name, id, placeholderText = "Type valid email and press enter", isDisabled, isReadOnly, addOnBlur = false, size = DEFAULT_CONTROL_SIZE, inputStyle, helperText, error, errorMessage, }) {
     const theme = useCustomTheme();
     const s = getSearchSelectSizeStyles((size || DEFAULT_CONTROL_SIZE));