pixelize-design-library 2.4.2-beta.9 → 3.0.0

package/dist/Components/FilterSidebar/filterHoverStyle.js

@@ -1,14 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFilterHoverBg = void 0;
-/**
- * FilterSidebar's hover fill for option rows, popover list items, and the accordion trigger.
- * `gray[50]` (a pale near-white tint in light mode) sits within ~1 lightness point of the
- * dark-mode canvas once the whole scale flips (~1.08:1 contrast) — invisible, the QA-reported
- * "checkbox hover invisible" bug. `gray[300]` clears the resting canvas (~2.3:1, a clear visible
- * cue) while staying dark enough that the existing `gray[700]`/`gray[800]` row text (tuned for a
- * near-black canvas) still reads at/above AA (~4.9:1+) on top of it — no text-color flip needed
- * here, unlike the Table row hover fix.
- */
-const getFilterHoverBg = (colors, isDark) => isDark ? colors.gray[300] : colors.gray[50];
+const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
+/** Shared with every selectable list row — never seed from `primary[500]` or `primary.opacity[8]`. */
+const getFilterHoverBg = (colors) => (0, rowStates_1.listRowBackgrounds)(colors).active;
 exports.getFilterHoverBg = getFilterHoverBg;

package/dist/Components/FilterSidebar/useStableCallback.d.ts

@@ -0,0 +1 @@
+export declare const useStableCallback: <A extends unknown[], R>(fn: (...args: A) => R) => ((...args: A) => R);

package/dist/Components/FilterSidebar/useStableCallback.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useStableCallback = void 0;
+const react_1 = require("react");
+const useStableCallback = (fn) => {
+    const latest = (0, react_1.useRef)(fn);
+    (0, react_1.useLayoutEffect)(() => {
+        latest.current = fn;
+    });
+    return (0, react_1.useCallback)((...args) => latest.current(...args), []);
+};
+exports.useStableCallback = useStableCallback;

package/dist/Components/Form/FormWrapper.d.ts

@@ -1,7 +1,10 @@
-import React, { ElementType } from "react";
-declare const FormWrapper: ({ icon, text, children, }: {
-    icon?: ElementType;
+import React, { ElementType, ReactElement } from "react";
+type FormWrapperProps = Omit<React.ComponentPropsWithoutRef<"div">, "children"> & {
+    /** A component reference (FiUser) or a rendered element (<FiUser />); an element is sized to 1rem by its wrapper. */
+    icon?: ElementType | ReactElement;
     text?: string;
     children: React.ReactNode;
-}) => import("react/jsx-runtime").JSX.Element;
+};
+/** Renders an icon+label header above a bordered card — not an HTML form; no submit/validation, just a section wrapper. id, data-* and aria-* land on the outer wrapper. */
+declare const FormWrapper: ({ icon, text, children, ...rest }: FormWrapperProps) => import("react/jsx-runtime").JSX.Element;
 export default FormWrapper;

package/dist/Components/Form/FormWrapper.js

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
+const react_2 = require("react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
-const FormWrapper = ({ icon, text, children, }) => {
+const isElement = (icon) => (0, react_2.isValidElement)(icon);
+/** Renders an icon+label header above a bordered card — not an HTML form; no submit/validation, just a section wrapper. id, data-* and aria-* land on the outer wrapper. */
+const FormWrapper = ({ icon, text, children, ...rest }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
-    return ((0, jsx_runtime_1.jsxs)(react_1.Box, { children: [(0, jsx_runtime_1.jsxs)(react_1.Box, { display: "flex", alignItems: "center", gap: 2, mb: 2, children: [icon && (0, jsx_runtime_1.jsx)(react_1.Icon, { as: icon, size: "1rem", color: colors.header[500] }), text && ((0, jsx_runtime_1.jsx)(react_1.Box, { fontFamily: "open-sans, sans-serif", fontWeight: 600, fontSize: 12, lineHeight: "100%", letterSpacing: "4%", textTransform: "uppercase", color: colors.header[500], children: text }))] }), (0, jsx_runtime_1.jsx)(react_1.Box, { borderRadius: "base", bg: colors.background[50], border: `0.075rem solid ${colors.boxborder[200]}`, boxShadow: `0 0.063rem 0.125rem 0 ${colors.boxShadow.primary}`, p: "1.5rem", children: children })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_1.Box, { ...rest, children: [(0, jsx_runtime_1.jsxs)(react_1.Box, { display: "flex", alignItems: "center", gap: 2, mb: 2, children: [isElement(icon) ? ((0, jsx_runtime_1.jsx)(react_1.Box, { display: "inline-flex", boxSize: "1rem", color: colors.header[500], sx: { "& > svg": { width: "100%", height: "100%" } }, children: icon })) : (icon && (0, jsx_runtime_1.jsx)(react_1.Icon, { as: icon, boxSize: "1rem", color: colors.header[500] })), text && ((0, jsx_runtime_1.jsx)(react_1.Box, { fontWeight: 600, fontSize: "xs", lineHeight: "1", textTransform: "uppercase", color: colors.header[500], children: text }))] }), (0, jsx_runtime_1.jsx)(react_1.Box, { borderRadius: "xl", bg: colors.background[50], borderWidth: "1px", borderStyle: "solid", borderColor: colors.boxborder[200], p: "1.5rem", children: children })] }));
 };
 exports.default = FormWrapper;

package/dist/Components/FormDrawer/FormDrawer.d.ts

@@ -0,0 +1,3 @@
+import type { FormDrawerProps } from "./FormDrawerProps";
+/** 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, isSubmitDisabled, submitLabel, cancelLabel, secondaryAction, size, labels, "data-testid": testId, }: FormDrawerProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/FormDrawer/FormDrawer.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = FormDrawer;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("@chakra-ui/react");
+const Drawer_1 = __importStar(require("../Drawer/Drawer"));
+const AlertDialog_1 = __importDefault(require("../AlertDialog/AlertDialog"));
+const Button_1 = __importDefault(require("../Button/Button"));
+const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const DEFAULT_LABELS = {
+    fixErrors: "Please fix the following before saving",
+    discardTitle: "Discard changes?",
+    discardBody: "You have unsaved changes. If you close now, they will be lost.",
+    discard: "Discard",
+    keepEditing: "Keep editing",
+};
+/** Sectioned create/edit form in a Drawer with error summary, sticky footer and discard-changes confirm. */
+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 } = (0, useCustomTheme_1.useCustomTheme)();
+    const uid = (0, react_1.useId)();
+    const formId = `${uid}-form`;
+    const titleId = `${uid}-title`;
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const [confirmDiscard, setConfirmDiscard] = (0, react_1.useState)(false);
+    const [attempt, setAttempt] = (0, react_1.useState)(0);
+    const keepEditingRef = (0, react_1.useRef)(null);
+    const summaryRef = (0, react_1.useRef)(null);
+    const focusPending = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (!isOpen)
+            setConfirmDiscard(false);
+    }, [isOpen]);
+    (0, react_1.useEffect)(() => {
+        var _a;
+        if (!focusPending.current || isSubmitting)
+            return;
+        focusPending.current = false;
+        if (errors.length)
+            (_a = summaryRef.current) === null || _a === void 0 ? void 0 : _a.focus();
+    }, [attempt, errors, isSubmitting]);
+    const requestClose = () => {
+        if (isSubmitting)
+            return;
+        if (isDirty)
+            setConfirmDiscard(true);
+        else
+            onClose();
+    };
+    const submit = (event) => {
+        event.preventDefault();
+        if (isSubmitting || isSubmitDisabled)
+            return;
+        focusPending.current = true;
+        setAttempt((n) => n + 1);
+        onSubmit();
+    };
+    return ((0, jsx_runtime_1.jsxs)(Drawer_1.default, { isOpen: isOpen, onClose: requestClose, size: size, closeOnEsc: !isSubmitting, closeOnOverlayClick: !isSubmitting, portalChildren: (0, jsx_runtime_1.jsx)(AlertDialog_1.default, { isOpen: confirmDiscard, onClose: () => setConfirmDiscard(false), leastDestructiveRef: keepEditingRef, isCentered: true, tone: "danger", title: text.discardTitle, content: (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: "sm", color: colors.text[800], children: text.discardBody }), cancelButtonText: text.keepEditing, confirmButtonText: text.discard, onConfirm: () => {
+                setConfirmDiscard(false);
+                onClose();
+            } }), children: [(0, jsx_runtime_1.jsxs)(Drawer_1.DrawerHeader, { children: [(0, jsx_runtime_1.jsx)(react_2.Heading, { id: titleId, as: "h2", fontSize: "md", fontWeight: 600, color: colors.header[900], children: title }), description ? ((0, jsx_runtime_1.jsx)(react_2.Text, { mt: 0.5, fontSize: "sm", fontWeight: 400, color: colors.textMuted, children: description })) : null] }), (0, jsx_runtime_1.jsx)(Drawer_1.DrawerBody, { children: (0, jsx_runtime_1.jsx)(react_2.Box, { as: "form", id: formId, "aria-labelledby": titleId, onSubmit: submit, noValidate: true, "data-testid": testId, children: (0, jsx_runtime_1.jsxs)(react_2.Flex, { direction: "column", gap: 5, pt: 2, children: [errors.length ? ((0, jsx_runtime_1.jsxs)(react_2.Alert, { ref: summaryRef, tabIndex: -1, status: "error", variant: "subtle", borderRadius: "md", alignItems: "flex-start", "data-testid": `${testId}-errors`, children: [(0, jsx_runtime_1.jsx)(react_2.AlertIcon, {}), (0, jsx_runtime_1.jsxs)(react_2.Box, { children: [(0, jsx_runtime_1.jsx)(react_2.AlertTitle, { fontSize: "sm", children: text.fixErrors }), (0, jsx_runtime_1.jsx)(react_2.AlertDescription, { fontSize: "sm", children: (0, jsx_runtime_1.jsx)(react_2.UnorderedList, { mt: 1, children: errors.map((message) => ((0, jsx_runtime_1.jsx)(react_2.ListItem, { children: message }, message))) }) })] })] })) : null, sections.map((section, index) => ((0, jsx_runtime_1.jsxs)(react_1.Fragment, { children: [index > 0 ? (0, jsx_runtime_1.jsx)(react_2.Divider, { borderColor: colors.boxborder[200] }) : null, (0, jsx_runtime_1.jsxs)(react_2.Flex, { as: "section", direction: "column", gap: 4, "aria-label": section.title, children: [section.title ? ((0, jsx_runtime_1.jsxs)(react_2.Box, { children: [(0, jsx_runtime_1.jsx)(react_2.Heading, { as: "h3", fontSize: "sm", fontWeight: 600, color: colors.header[900], children: section.title }), section.description ? ((0, jsx_runtime_1.jsx)(react_2.Text, { mt: 0.5, fontSize: "xs", color: colors.textMuted, children: section.description })) : null] })) : null, section.content] })] }, section.id)))] }) }) }), (0, jsx_runtime_1.jsx)(Drawer_1.DrawerFooter, { children: (0, jsx_runtime_1.jsxs)(react_2.Flex, { gap: 2, w: "100%", justify: "flex-end", wrap: "wrap", children: [secondaryAction, (0, jsx_runtime_1.jsx)(Button_1.default, { variant: "ghost", colorScheme: "gray", onClick: requestClose, isDisabled: isSubmitting, label: cancelLabel }), (0, jsx_runtime_1.jsx)(Button_1.default, { variant: "solid", colorScheme: "primary", type: "submit", form: formId, isLoading: isSubmitting, isDisabled: isSubmitDisabled, loadingText: submitLabel, label: submitLabel, "data-testid": `${testId}-submit` })] }) })] }));
+}

package/dist/Components/FormDrawer/FormDrawerProps.d.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+/** One block of the form; sections after the first are separated by a divider. */
+export type FormDrawerSection = {
+    /** Stable React key. */
+    id: string;
+    /** Renders an h3 above the content; also names the section region. */
+    title?: string;
+    /** Muted line under `title`; ignored without a title. */
+    description?: string;
+    /** Body of the section, rendered below its title and description. */
+    content: ReactNode;
+};
+/** Every user-facing string FormDrawer owns; pass the ones you localise. */
+export type FormDrawerLabels = {
+    /** Heading of the error summary. Defaults to "Please fix the following before saving". */
+    fixErrors: string;
+    /** Defaults to "Discard changes?". */
+    discardTitle: string;
+    /** Defaults to "You have unsaved changes. If you close now, they will be lost.". */
+    discardBody: string;
+    /** Confirm button of the discard dialog. Defaults to "Discard". */
+    discard: string;
+    /** Cancel button of the discard dialog, focused on open. Defaults to "Keep editing". */
+    keepEditing: string;
+};
+/** Sectioned create/edit form in a Drawer: error summary, sticky footer, and a discard-changes confirm when closing while dirty. */
+export interface FormDrawerProps {
+    /** Controlled open state; the drawer stays closed until this is true. */
+    isOpen: boolean;
+    /** Called once the user has really closed: clean close, or Discard confirmed. Never called while `isSubmitting`. */
+    onClose: () => void;
+    /** Drawer heading; also the accessible name of the dialog and of the form. */
+    title: string;
+    /** Muted line under the title. */
+    description?: string;
+    /** Form blocks rendered top to bottom in array order. */
+    sections: FormDrawerSection[];
+    /** Validation messages shown as a summary above the form; the summary takes focus after a submit that leaves any. */
+    errors?: string[];
+    /** Closing (X, Esc, overlay, Cancel) asks for confirmation while true. */
+    isDirty: boolean;
+    /** Fires on submit (button or Enter in a field); the browser's own validation is off, so validate in the handler. */
+    onSubmit: () => void;
+    /** Spins the submit button, disables Cancel and blocks every close path. Set it synchronously in `onSubmit` so error focus waits for the result. */
+    isSubmitting?: boolean;
+    /** Disables the primary button and swallows Enter and any other form submit, so `onSubmit` never fires; unlike `isSubmitting`, Cancel and every close path stay live. */
+    isSubmitDisabled?: boolean;
+    /** Defaults to "Save". */
+    submitLabel?: string;
+    /** Defaults to "Cancel". */
+    cancelLabel?: string;
+    /** Rendered left of Cancel, e.g. a ghost "Save as draft" Button. */
+    secondaryAction?: ReactNode;
+    /** Drawer width. Defaults to "md". */
+    size?: "sm" | "md" | "lg";
+    /** Overrides for the built-in strings. */
+    labels?: Partial<FormDrawerLabels>;
+    /** Set on the form; the error summary and submit button get `-errors` / `-submit` suffixes. Defaults to "form-drawer". */
+    "data-testid"?: string;
+}

package/dist/Components/FormDrawer/FormDrawerProps.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Components/FormField/FormField.d.ts

@@ -0,0 +1,4 @@
+import type { FormFieldProps } from "./FormFieldProps";
+/** Wires a label, required marker, helper and error text to one control through ids and aria attributes. */
+declare const FormField: import("react").ForwardRefExoticComponent<FormFieldProps & import("react").RefAttributes<HTMLDivElement>>;
+export default FormField;

package/dist/Components/FormField/FormField.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("@chakra-ui/react");
+const ErrorMessage_1 = __importDefault(require("../Common/ErrorMessage"));
+const FormLabel_1 = require("../Common/FormLabel");
+const fieldMessageStyles_1 = require("../Common/fieldMessageStyles");
+const useFieldIds_1 = require("../Common/useFieldIds");
+const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const joinIds = (...ids) => [...new Set(ids.flatMap((value) => { var _a; return (_a = value === null || value === void 0 ? void 0 : value.split(/\s+/)) !== null && _a !== void 0 ? _a : []; }).filter(Boolean))].join(" ") || undefined;
+const asWirableElement = (children) => typeof children !== "function" && (0, react_1.isValidElement)(children) && children.type !== react_1.Fragment
+    ? children
+    : undefined;
+/** Wires a label, required marker, helper and error text to one control through ids and aria attributes. */
+const FormField = (0, react_1.forwardRef)(function FormField({ label, id, isRequired = false, error = false, errorMessage, helperText, layout = "vertical", labelWidth = "12rem", children, ...rest }, ref) {
+    var _a;
+    const { colors } = (0, useCustomTheme_1.useCustomTheme)();
+    const element = asWirableElement(children);
+    const own = (_a = element === null || element === void 0 ? void 0 : element.props) !== null && _a !== void 0 ? _a : {};
+    const ids = (0, useFieldIds_1.useFieldIds)(id !== null && id !== void 0 ? id : own.id, { error, errorMessage, helperText });
+    const { showError, showHelper } = (0, fieldMessageStyles_1.fieldMessageVisibility)({ error, errorMessage, helperText });
+    const describedBy = joinIds(own["aria-describedby"], ids.describedBy);
+    const control = {
+        id: ids.inputId,
+        "aria-labelledby": ids.labelId,
+        "aria-describedby": describedBy,
+        "aria-invalid": ids.controlProps["aria-invalid"],
+        "aria-required": isRequired || undefined,
+    };
+    const isSelfNamed = Boolean(own["aria-label"] || own["aria-labelledby"]);
+    const wired = element
+        ? (0, react_1.cloneElement)(element, {
+            id: control.id,
+            ...(isSelfNamed ? {} : { "aria-labelledby": control["aria-labelledby"] }),
+            ...(describedBy ? { "aria-describedby": describedBy } : {}),
+            ...(error ? { "aria-invalid": true } : {}),
+            ...(isRequired ? { "aria-required": true } : {}),
+        })
+        : typeof children === "function"
+            ? children(control)
+            : children;
+    const message = showError && errorMessage ? ((0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { id: ids.errorId, errorMessage: errorMessage })) : showHelper ? ((0, jsx_runtime_1.jsx)(react_2.Box, { id: ids.helperId, ...(0, fieldMessageStyles_1.fieldMessageStyles)(colors), children: helperText })) : null;
+    const isHorizontal = layout === "horizontal";
+    const labelStyles = (0, FormLabel_1.fieldLabelStyles)(colors);
+    return ((0, jsx_runtime_1.jsxs)(react_2.FormControl, { ...rest, ref: ref, id: ids.inputId, isRequired: isRequired, isInvalid: error, ...(isHorizontal
+            ? {
+                display: "grid",
+                gridTemplateColumns: { base: "minmax(0, 1fr)", md: `${labelWidth} minmax(0, 1fr)` },
+                columnGap: 4,
+                alignItems: "start",
+            }
+            : {}), children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "label", id: ids.labelId, htmlFor: ids.inputId, ...labelStyles, display: "block", ...(isHorizontal ? { alignSelf: { md: "center" }, mb: { base: labelStyles.mb, md: 0 } } : {}), children: (0, jsx_runtime_1.jsxs)(react_2.Box, { as: "span", display: "inline-flex", alignItems: "center", gap: "0.35rem", children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", children: label }), isRequired && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": "true", color: colors.semanticText.error, ml: "0.125rem", children: "*" }))] }) }), isHorizontal ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_2.Box, { minW: 0, children: wired }), message && (0, jsx_runtime_1.jsx)(react_2.Box, { gridColumn: { md: 2 }, children: message })] })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [wired, message] }))] }));
+});
+exports.default = FormField;

package/dist/Components/FormField/FormFieldProps.d.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes, ReactElement, ReactNode } from "react";
+/** The wiring FormField hands its control; spread it onto the focusable element. */
+export interface FormFieldControlProps {
+    /** Id for the control; the label, helper and error ids derive from it. */
+    id: string;
+    /** Points at the field's label element, so composites that a `<label for>` cannot name still get one. */
+    "aria-labelledby": string;
+    /** The error when shown, else the helper text, plus any description the child already had. */
+    "aria-describedby": string | undefined;
+    /** True while `error` is set, else undefined. */
+    "aria-invalid": true | undefined;
+    /** True when the field is required, else undefined. */
+    "aria-required": true | undefined;
+}
+/** Where the label sits relative to the control. */
+export type FormFieldLayout = "vertical" | "horizontal";
+/** Label, required marker, helper text and error message around any one control; other `<div>` attributes land on the root. */
+export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "id" | "children" | "color" | "dangerouslySetInnerHTML"> {
+    /** Label text, shown beside or above the control. */
+    label: string;
+    /** The control's id, which the label and message ids derive from; defaults to the child element's own `id`, else a generated one. */
+    id?: string;
+    /** Adds the asterisk, `aria-required` on the control, and Chakra's `isRequired` for Chakra-based controls (which also sets native `required`). */
+    isRequired?: boolean;
+    /** Marks the control `aria-invalid` and shows `errorMessage` in place of `helperText`. */
+    error?: boolean;
+    /** Shown, and announced, only while `error` is true. */
+    errorMessage?: string;
+    /** Shown under the control whenever no error is showing. */
+    helperText?: string;
+    /** "vertical" (default) stacks label over control; "horizontal" puts the label in a left column from the `md` breakpoint up and stacks below it. */
+    layout?: FormFieldLayout;
+    /** Width of the label column in the horizontal layout; defaults to "12rem". */
+    labelWidth?: string;
+    /** One element, which receives the wiring as props, or a function that places it on the right element of a composite control. */
+    children: ReactElement | ((control: FormFieldControlProps) => ReactNode);
+}

package/dist/Components/FormField/FormFieldProps.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Components/Header/Header.d.ts

@@ -1,21 +1,7 @@
 import { FC } from "react";
 import type { ColorScale } from "../../Theme/tokens/types";
 import { HeaderProps } from "./HeaderProps";
-/**
- * Header's sidebar canvas (`bg`) is always dark regardless of app mode — `buildDarkPalette`
- * deliberately leaves `sidebar` unchanged ("already near-black in light mode, so it needs no
- * inversion"). But `themeColor.primary` follows whichever mode is active, so it can be either
- * light-mode-shaped (50 lightest -> 900 darkest) or dark-mode-shaped (50 darkest -> 900 lightest).
- * `accentTextOnCanvas` picks its search direction from the CANVAS's darkness, assuming that always
- * implies a dark-mode-shaped scale — true everywhere else (canvas darkness there tracks app mode),
- * false here, where the canvas never inverts but the scale still does. Walking toward 900 on a
- * light-mode-shaped scale therefore walks toward darker, not lighter, and can land near-black.
- *
- * This detects the scale's own direction from its own data (`primary[50]` vs `primary[900]`
- * luminance) rather than from the canvas or from theme-mode context, so it's correct in both app
- * modes and has no dependency on being mounted inside `PixelizeThemeProvider` (Header must keep
- * working for legacy `withTheme`-only consumers too).
- */
 export declare const pickActiveAccent: (primary: ColorScale, canvas: string) => string;
+/** Sticky top bar with logo, page links, hover dropdowns and a collapsible mobile menu; colours default to the sidebar tokens. */
 declare const Header: FC<HeaderProps>;
 export default Header;

package/dist/Components/Header/Header.js

@@ -48,21 +48,7 @@ const desktopMenu_1 = __importDefault(require("./components/desktopMenu"));
 const mobileMenu_1 = __importDefault(require("./components/mobileMenu"));
 /** Non-text UI accent (WCAG 1.4.11, >=3:1) — the underline/highlight, not running text. */
 const ACTIVE_ACCENT_TARGET = 3;
-/**
- * Header's sidebar canvas (`bg`) is always dark regardless of app mode — `buildDarkPalette`
- * deliberately leaves `sidebar` unchanged ("already near-black in light mode, so it needs no
- * inversion"). But `themeColor.primary` follows whichever mode is active, so it can be either
- * light-mode-shaped (50 lightest -> 900 darkest) or dark-mode-shaped (50 darkest -> 900 lightest).
- * `accentTextOnCanvas` picks its search direction from the CANVAS's darkness, assuming that always
- * implies a dark-mode-shaped scale — true everywhere else (canvas darkness there tracks app mode),
- * false here, where the canvas never inverts but the scale still does. Walking toward 900 on a
- * light-mode-shaped scale therefore walks toward darker, not lighter, and can land near-black.
- *
- * This detects the scale's own direction from its own data (`primary[50]` vs `primary[900]`
- * luminance) rather than from the canvas or from theme-mode context, so it's correct in both app
- * modes and has no dependency on being mounted inside `PixelizeThemeProvider` (Header must keep
- * working for legacy `withTheme`-only consumers too).
- */
+// NOTE: sidebar canvas never inverts but primary can be either mode-shaped — direction is detected from primary's own data, not the canvas.
 const pickActiveAccent = (primary, canvas) => {
     const runsDarkToLight = (0, color_1.relativeLuminance)(primary[50]) < (0, color_1.relativeLuminance)(primary[900]);
     const order = runsDarkToLight
@@ -72,6 +58,7 @@ const pickActiveAccent = (primary, canvas) => {
     return primary[found !== null && found !== void 0 ? found : order[order.length - 1]];
 };
 exports.pickActiveAccent = pickActiveAccent;
+/** 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 } = (0, react_1.useDisclosure)();
@@ -90,6 +77,6 @@ const Header = ({ logo, menuItems, rightSlot, active, colors, boxShadow, onMobil
     const rightSlotWithApi = react_2.default.isValidElement(rightSlot)
         ? react_2.default.cloneElement(rightSlot, { closeMobileMenu })
         : rightSlot;
-    return ((0, jsx_runtime_1.jsxs)(react_1.Box, { bg: bg, color: color, px: 4, shadow: "md", boxShadow: boxShadow, zIndex: 1000, position: "sticky", children: [(0, jsx_runtime_1.jsxs)(react_1.Flex, { h: Sidebar_1.HEADER_HEIGHT, align: "center", mx: "auto", justifyContent: "flex-start", children: [(0, jsx_runtime_1.jsxs)(react_1.HStack, { spacing: 6, align: "center", children: [(0, jsx_runtime_1.jsx)(react_1.Box, { cursor: "pointer", children: logo }), (0, jsx_runtime_1.jsx)(desktopMenu_1.default, { menuItems: menuItems, rightSlot: rightSlotWithApi, setHoveredMenu: setHoveredMenu, isActive: isActive, activeBg: activeBg, hoveredMenu: hoveredMenu, hoverBg: hoverBg, color: color, hoverTextColor: hoverText })] }), (0, jsx_runtime_1.jsx)(react_1.Spacer, {}), (0, jsx_runtime_1.jsxs)(react_1.HStack, { spacing: 3, align: "center", children: [(0, jsx_runtime_1.jsx)(react_1.HStack, { spacing: 4, display: { base: "none", md: "flex" }, children: rightSlotWithApi }), (0, jsx_runtime_1.jsx)(react_1.HStack, { spacing: 2, display: { base: "flex", md: "none" }, children: rightSlotWithApi }), (0, jsx_runtime_1.jsx)(react_1.IconButton, { variant: "unstyled", icon: (0, jsx_runtime_1.jsx)(react_1.Box, { display: "flex", alignItems: "center", justifyContent: "center", w: "full", h: "full", children: isOpen ? (0, jsx_runtime_1.jsx)(lucide_react_1.X, { size: 20 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.MenuIcon, { size: 20 }) }), "aria-label": "Toggle Menu", display: { md: "none" }, onClick: isOpen ? closeMobileMenu : onOpen })] })] }), (0, jsx_runtime_1.jsx)(mobileMenu_1.default, { menuItems: menuItems, isOpen: isOpen, isActive: isActive, hoverBg: hoverBg, activeBg: activeBg, color: color, rightSlot: rightSlotWithApi, onClose: closeMobileMenu })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_1.Box, { bg: bg, color: color, px: 4, shadow: "md", boxShadow: boxShadow, zIndex: "sticky", position: "sticky", top: 0, children: [(0, jsx_runtime_1.jsxs)(react_1.Flex, { minH: Sidebar_1.HEADER_HEIGHT, align: "center", mx: "auto", justifyContent: "flex-start", children: [(0, jsx_runtime_1.jsxs)(react_1.HStack, { spacing: 6, align: "center", children: [(0, jsx_runtime_1.jsx)(react_1.Box, { cursor: "pointer", children: logo }), (0, jsx_runtime_1.jsx)(desktopMenu_1.default, { menuItems: menuItems, rightSlot: rightSlotWithApi, setHoveredMenu: setHoveredMenu, isActive: isActive, activeBg: activeBg, hoveredMenu: hoveredMenu, hoverBg: hoverBg, color: color, hoverTextColor: hoverText, surface: bg })] }), (0, jsx_runtime_1.jsx)(react_1.Spacer, {}), (0, jsx_runtime_1.jsxs)(react_1.HStack, { spacing: 3, align: "center", children: [(0, jsx_runtime_1.jsx)(react_1.HStack, { spacing: { base: 2, md: 4 }, children: rightSlotWithApi }), (0, jsx_runtime_1.jsx)(react_1.IconButton, { variant: "unstyled", icon: (0, jsx_runtime_1.jsx)(react_1.Box, { display: "flex", alignItems: "center", justifyContent: "center", w: "full", h: "full", children: isOpen ? (0, jsx_runtime_1.jsx)(lucide_react_1.X, { size: 20 }) : (0, jsx_runtime_1.jsx)(lucide_react_1.MenuIcon, { size: 20 }) }), "aria-label": "Toggle Menu", display: { md: "none" }, onClick: isOpen ? closeMobileMenu : onOpen })] })] }), (0, jsx_runtime_1.jsx)(mobileMenu_1.default, { menuItems: menuItems, isOpen: isOpen, isActive: isActive, hoverBg: hoverBg, activeBg: activeBg, color: color, surface: bg, onClose: closeMobileMenu })] }));
 };
 exports.default = Header;

package/dist/Components/Header/HeaderActions.d.ts

@@ -1,23 +1,43 @@
 import { OptionProp } from "../Select/SelectProps";
+/** Row of optional header controls (select, edit, create) separated by dividers; each renders only when its flag is set. */
 declare const HeaderActions: ({ select, edit, create, surface, }: {
     /** Background this is drawn on. Header's bar is dark in BOTH modes — pass it there. */
     surface?: string;
+    /** Optional select shown at the start of the row. */
     select?: {
+        /** Renders the select only when true. */
         isSelect?: boolean;
+        /** Options of the select; empty when omitted. */
         options?: OptionProp[];
+        /** Called with the chosen option. */
         onSelectChange?: (option?: OptionProp) => void;
+        /** Placeholder of the select; also its accessible name when `ariaLabel` is not set. */
         selectPlaceholderText?: string;
+        /** Accessible name for the select; defaults to the placeholder text. */
+        ariaLabel?: string;
+        /** False renders the themed popup, which looks identical on Windows and macOS; a native select's list is OS-drawn. */
+        native?: boolean;
+        /** CSS width of the select wrapper; defaults to "12.5rem". */
         width?: string;
+        /** Value of the selected option. */
         value?: string;
     };
+    /** Optional text button with a pencil icon. */
     edit?: {
+        /** Renders the button only when true. */
         isEditable?: boolean;
+        /** Called when the button is pressed. */
         onEdit?: () => void;
+        /** Button text; defaults to "Edit Layout". */
         label?: string;
     };
+    /** Optional text button with a plus icon. */
     create?: {
+        /** Renders the button only when true. */
         isCreatable?: boolean;
+        /** Called when the button is pressed. */
         onCreate?: () => void;
+        /** Button text; defaults to "Create New". */
         label?: string;
     };
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/Components/Header/HeaderActions.js

@@ -12,21 +12,24 @@ const accentText_1 = require("../../Theme/tokens/builders/accentText");
 const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
 const Select_1 = __importDefault(require("../Select/Select"));
 const Divider_1 = __importDefault(require("../Divider/Divider"));
+const surfaceFocusRing_1 = require("../Common/surfaceFocusRing");
+/** 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;
+    var _a, _b, _c;
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const canvas = surface !== null && surface !== void 0 ? surface : colors.backgroundColor.main;
     const ink = (0, outlineRung_1.liftToContrast)(colors.secondary[500], canvas, accentText_1.AA_NORMAL_TEXT);
     const iconInk = (0, outlineRung_1.liftToContrast)(colors.secondary[500], canvas, outlineRung_1.AA_NON_TEXT);
+    const focusShadow = (0, surfaceFocusRing_1.surfaceFocusRing)(canvas, iconInk);
     const elements = [];
     if (select === null || select === void 0 ? void 0 : select.isSelect) {
-        elements.push((0, jsx_runtime_1.jsx)(react_1.Box, { width: (_a = select.width) !== null && _a !== void 0 ? _a : "12.5rem", children: (0, jsx_runtime_1.jsx)(Select_1.default, { options: (_b = select.options) !== null && _b !== void 0 ? _b : [], placeholder: select.selectPlaceholderText, onChange: (option) => { var _a; return (_a = select.onSelectChange) === null || _a === void 0 ? void 0 : _a.call(select, option); }, value: select.value }, "select") }, "select"));
+        elements.push((0, jsx_runtime_1.jsx)(react_1.Box, { width: (_a = select.width) !== null && _a !== void 0 ? _a : "12.5rem", children: (0, jsx_runtime_1.jsx)(Select_1.default, { options: (_b = select.options) !== null && _b !== void 0 ? _b : [], placeholder: select.selectPlaceholderText, "aria-label": select.ariaLabel || select.selectPlaceholderText || "Select", native: (_c = select.native) !== null && _c !== void 0 ? _c : false, onChange: (option) => { var _a; return (_a = select.onSelectChange) === null || _a === void 0 ? void 0 : _a.call(select, option); }, value: select.value }, "select") }, "select"));
     }
     if (edit === null || edit === void 0 ? void 0 : edit.isEditable) {
-        elements.push((0, jsx_runtime_1.jsxs)(react_1.Box, { display: "flex", alignItems: "center", gap: "0.375rem", cursor: "pointer", fontSize: 14, onClick: () => { var _a; return (_a = edit.onEdit) === null || _a === void 0 ? void 0 : _a.call(edit); }, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.SquarePen, { size: 16, color: iconInk }), (0, jsx_runtime_1.jsx)(react_1.Text, { color: ink, children: edit.label ? edit.label : "Edit Layout" })] }, "edit"));
+        elements.push((0, jsx_runtime_1.jsxs)(react_1.Box, { as: "button", type: "button", bg: "transparent", borderRadius: "lg", _focusVisible: { boxShadow: focusShadow, outline: "none" }, display: "flex", alignItems: "center", gap: "0.375rem", cursor: "pointer", fontSize: "sm", onClick: () => { var _a; return (_a = edit.onEdit) === null || _a === void 0 ? void 0 : _a.call(edit); }, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.SquarePen, { size: 16, color: iconInk }), (0, jsx_runtime_1.jsx)(react_1.Text, { color: ink, children: edit.label ? edit.label : "Edit Layout" })] }, "edit"));
     }
     if (create === null || create === void 0 ? void 0 : create.isCreatable) {
-        elements.push((0, jsx_runtime_1.jsxs)(react_1.Box, { display: "flex", alignItems: "center", gap: "0.375rem", cursor: "pointer", fontSize: 14, onClick: () => { var _a; return (_a = create.onCreate) === null || _a === void 0 ? void 0 : _a.call(create); }, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.CirclePlus, { size: 16, color: iconInk }), (0, jsx_runtime_1.jsxs)(react_1.Text, { color: ink, children: [" ", create.label ? create.label : "Create New", " "] })] }, "create"));
+        elements.push((0, jsx_runtime_1.jsxs)(react_1.Box, { as: "button", type: "button", bg: "transparent", borderRadius: "lg", _focusVisible: { boxShadow: focusShadow, outline: "none" }, display: "flex", alignItems: "center", gap: "0.375rem", cursor: "pointer", fontSize: "sm", onClick: () => { var _a; return (_a = create.onCreate) === null || _a === void 0 ? void 0 : _a.call(create); }, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.CirclePlus, { size: 16, color: iconInk }), (0, jsx_runtime_1.jsxs)(react_1.Text, { color: ink, children: [" ", create.label ? create.label : "Create New", " "] })] }, "create"));
     }
     return ((0, jsx_runtime_1.jsx)(react_1.Box, { display: "flex", alignItems: "center", gap: "0.625rem", children: elements.map((el, i) => ((0, jsx_runtime_1.jsxs)(react_2.default.Fragment, { children: [i > 0 && (0, jsx_runtime_1.jsx)(Divider_1.default, {}), el] }, i))) }));
 };

package/dist/Components/Header/HeaderProps.d.ts

@@ -1,48 +1,88 @@
+/** Horizontal top bar with page-link nav + submenus — for a user-avatar dropdown bar instead, use NavigationBar. */
 type SubItem = {
+    /** Dropdown entry text; also its React key, so keep it unique within the parent. */
     label: string;
+    /** Only compared with Header's `active` to highlight — never navigates; route in `onClick`. */
     href: string;
+    /** Small badge above the label; colorScheme defaults to "blue". */
     badge?: {
+        /** Badge text. */
         label: string;
+        /** Chakra colour scheme of the badge; the tint is resolved against the bar background. */
         colorScheme?: "blue" | "cyan" | "gray" | "green" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | "whiteAlpha" | "blackAlpha" | undefined;
     };
+    /** Also closes the mobile menu when tapped there. */
     onClick?: () => void;
 };
 type MenuItemProp = {
+    /** Top-level entry text; also its React key and what the hover dropdown is keyed on, so keep it unique. */
     label: string;
+    /** Only compared with Header's `active` to highlight — never navigates; route in `onClick`. */
     href?: string;
+    /** Small badge above the label; colorScheme defaults to "blue". */
     badge?: {
+        /** Badge text. */
         label: string;
+        /** Chakra colour scheme of the badge; the tint is resolved against the bar background. */
         colorScheme?: "blue" | "cyan" | "gray" | "green" | "orange" | "pink" | "purple" | "red" | "teal" | "yellow" | "whiteAlpha" | "blackAlpha" | undefined;
     };
+    /** Also closes the mobile menu; with `children`, fires on desktop only — mobile tap just toggles. */
     onClick?: () => void;
+    /** Opens as a hover-only dropdown on desktop (no click/keyboard trigger) — a click-toggled accordion on mobile instead. */
     children?: SubItem[];
 };
+/** Props for Header, the horizontal top bar; use NavigationBar for a user-avatar dropdown instead. */
 export type HeaderProps = {
+    /** Brand mark at the left of the bar; any click handling is yours to attach. */
     logo: React.ReactNode;
+    /** Top-level entries in order; an entry with `children` becomes a dropdown (desktop) or accordion (mobile). */
     menuItems: MenuItemProp[];
+    /** Mounted once, in the bar; a valid element also receives a `closeMobileMenu` prop. */
     rightSlot?: React.ReactNode;
+    /** The `href` of the item to highlight; matched by strict equality. */
     active?: string;
+    /** Overrides the sidebar-token defaults; `active` is the underline/highlight colour, not text. */
     colors?: {
+        /** Bar background. */
         bg: string;
+        /** Default text and icon colour. */
         color: string;
+        /** Underline on the active top-level item and fill behind the active sub-item. */
         active: string;
+        /** Background of an item under the pointer. */
         hover: string;
+        /** Text colour of an item under the pointer; defaults to white. */
         hoverTextColor?: string;
     };
+    /** Overrides the default "md" shadow. */
     boxShadow?: string;
+    /** Fires after the mobile menu closes via toggle, item tap, or `closeMobileMenu`. */
     onMobileMenuClose?: () => void;
 };
+/** Internal props for Header's desktop nav row; not meant for consumers. */
 export type DesktopMenuProps = Pick<HeaderProps, "menuItems" | "rightSlot"> & {
+    /** Called with the hovered item's label, or null on pointer leave; only items with children trigger it. */
     setHoveredMenu: (menu: string | null) => void;
+    /** True when an `href` matches Header's `active`. */
     isActive: (href?: string) => boolean | "" | undefined;
+    /** Underline or fill colour of the active item. */
     activeBg: string;
+    /** Label of the item whose dropdown is open, or null. */
     hoveredMenu: string | null;
+    /** Background of an item under the pointer. */
     hoverBg: string;
+    /** Default text colour. */
     color: string;
+    /** Text colour of an item under the pointer. */
     hoverTextColor?: string;
+    /** The bar's own background — badges resolve their tint against this, never the light canvas default. */
+    surface: string;
 };
-export type MobileMenuProps = Pick<HeaderProps, 'menuItems' | 'rightSlot'> & Pick<DesktopMenuProps, 'isActive' | 'activeBg' | 'color' | 'hoverBg'> & {
+/** Internal props for Header's collapsible mobile menu panel; not meant for consumers. */
+export type MobileMenuProps = Pick<HeaderProps, 'menuItems'> & Pick<DesktopMenuProps, 'isActive' | 'activeBg' | 'color' | 'hoverBg' | 'surface'> & {
+    /** Expands the panel; collapsing it also closes any open submenu. */
     isOpen: boolean;
+    /** Called after a leaf item is tapped, so the host can collapse the panel. */
     onClose?: () => void;
 };
 export {};

package/dist/Components/Header/components/desktopMenu.d.ts

@@ -1,3 +1,4 @@
 import { DesktopMenuProps } from "../HeaderProps";
-declare const DesktopMenu: ({ menuItems, rightSlot, setHoveredMenu, isActive, activeBg, hoveredMenu, hoverBg, color, hoverTextColor }: DesktopMenuProps) => import("react/jsx-runtime").JSX.Element;
+/** Desktop nav row of Header: ghost buttons with hover dropdowns for items that have children. */
+declare const DesktopMenu: ({ menuItems, rightSlot, setHoveredMenu, isActive, activeBg, hoveredMenu, hoverBg, color, hoverTextColor, surface, }: DesktopMenuProps) => import("react/jsx-runtime").JSX.Element;
 export default DesktopMenu;