@lutra-ui-system/react 0.1.0

package/dist/components/dropdown/dropdown.js

@@ -0,0 +1,173 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useId, useRef, useState } from 'react';
+import { Button } from '../button/index.js';
+/** Focusable things inside the panel, in DOM order. Disabled buttons are skipped by the browser. */
+const FOCUSABLE = 'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';
+/**
+ * A disclosure that reveals a panel of actions or links from a button.
+ *
+ * **It is a disclosure, not an ARIA menu, and that is deliberate.** The accessibility annotation is
+ * explicit: the trigger is a button, and the panel is a container of buttons or links depending on
+ * what each item does. No `role="menu"`, no `role="menuitem"`, and no arrow-key roving.
+ *
+ * The reason is that the two models cannot be mixed. A real ARIA menu promises arrow-key navigation
+ * *and* takes Tab away from the items inside it; a half-built one promises navigation that does not
+ * work, which is worse than no role at all. As a disclosure, everything inside keeps its native
+ * semantics and Tab keeps working, which is what the annotation asks for.
+ *
+ * Behaviour:
+ *
+ * - Enter or Space opens, because the trigger is a real button.
+ * - `aria-expanded` reflects the state and `aria-controls` points at the panel.
+ * - Focus moves to the first item on open.
+ * - Tab moves through the items in DOM order and out the other side.
+ * - Escape closes and returns focus to the trigger.
+ * - A pointer press outside closes it, without interfering with what was pressed.
+ * - Focus leaving the component closes it, so a Tab out does not strand an open panel.
+ *
+ * Open state is uncontrolled by default and controllable with `open` + `onOpenChange`, matching the
+ * pattern the form controls already use. There is no state machine beyond that.
+ */
+export function Dropdown({ label, icon, children, open: controlledOpen, defaultOpen = false, onOpenChange, triggerVariant = 'secondary', triggerSize = 'md', className, }) {
+    const panelId = `lutra-dropdown-${useId()}`;
+    const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+    const isControlled = controlledOpen !== undefined;
+    const open = isControlled ? controlledOpen : uncontrolledOpen;
+    const wrapperRef = useRef(null);
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    // Set when the component itself closes, so focus only returns to the trigger on those paths and
+    // not when a consumer closes it for their own reasons.
+    const returnFocus = useRef(false);
+    const setOpen = useCallback((next) => {
+        if (!isControlled)
+            setUncontrolledOpen(next);
+        onOpenChange?.(next);
+    }, [isControlled, onOpenChange]);
+    const close = useCallback(({ focusTrigger }) => {
+        returnFocus.current = focusTrigger;
+        setOpen(false);
+    }, [setOpen]);
+    // The trigger toggles, and one press must produce exactly one notification. It sets the
+    // focus-return flag directly rather than going through `close` first: closing and then opening
+    // would report `false` before `true` on the way open, and `false` twice on the way closed, which
+    // is a state change a consumer never asked for.
+    const toggle = useCallback(() => {
+        returnFocus.current = false;
+        setOpen(!open);
+    }, [open, setOpen]);
+    // Focus the first item on open; return focus to the trigger when the component closed itself.
+    useEffect(() => {
+        if (open) {
+            panelRef.current?.querySelector(FOCUSABLE)?.focus();
+            return;
+        }
+        if (returnFocus.current) {
+            returnFocus.current = false;
+            triggerRef.current?.focus();
+        }
+    }, [open]);
+    // A pointer press outside closes the panel. `pointerdown` rather than `click`, and nothing is
+    // prevented or stopped, so whatever was pressed still receives its own event normally.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (target instanceof Node && wrapperRef.current?.contains(target))
+                return;
+            close({ focusTrigger: false });
+        };
+        document.addEventListener('pointerdown', onPointerDown);
+        return () => {
+            document.removeEventListener('pointerdown', onPointerDown);
+        };
+    }, [open, close]);
+    // Escape and focus-loss are delegated with native listeners on the wrapper rather than JSX
+    // handlers. The wrapper is a positioning container, not something interactive, and hanging key
+    // handlers off a plain div is exactly what `jsx-a11y/no-static-element-interactions` objects to —
+    // rightly, because it usually means a div is pretending to be a control. Here the real handling
+    // belongs to the button and the items that bubble their events up, so delegation is the honest
+    // shape. `focusout` is used because, unlike `blur`, it bubbles.
+    useEffect(() => {
+        const wrapper = wrapperRef.current;
+        if (!open || !wrapper)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            // One press, one layer, through two different mechanisms.
+            //
+            // `preventDefault()` is for a native modal `<dialog>` above this panel: Escape reaching one is
+            // a *close request*, and the close-request algorithm only runs the close watcher when the
+            // keydown was not cancelled. Cancelling it says this press has been spent.
+            //
+            // `stopPropagation()` is for JavaScript layers that listen for the key themselves, which would
+            // otherwise act on the same press.
+            event.preventDefault();
+            event.stopPropagation();
+            close({ focusTrigger: true });
+        };
+        // Checked against the element receiving focus rather than a timer, so it is not fooled by focus
+        // moving between the panel's own items.
+        const onFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && wrapper.contains(next))
+                return;
+            close({ focusTrigger: false });
+        };
+        wrapper.addEventListener('keydown', onKeyDown);
+        wrapper.addEventListener('focusout', onFocusOut);
+        return () => {
+            wrapper.removeEventListener('keydown', onKeyDown);
+            wrapper.removeEventListener('focusout', onFocusOut);
+        };
+    }, [open, close]);
+    return (_jsxs("div", { ref: wrapperRef, className: className === undefined ? 'lutra-dropdown' : `lutra-dropdown ${className}`, children: [_jsx(Button, { ref: triggerRef, variant: triggerVariant, size: triggerSize, "aria-expanded": open, "aria-controls": panelId, onClick: toggle, ...(icon
+                    ? { contentType: 'icon-only', 'aria-label': label, children: icon }
+                    : { children: label }) }), open && (_jsx("div", { ref: panelRef, id: panelId, className: "lutra-dropdown__panel", children: children }))] }));
+}
+/**
+ * One item in a Dropdown panel.
+ *
+ * Renders a `<button>`, or an `<a>` when `href` is given. That is the whole of the semantic
+ * decision, and it follows the annotation: items that navigate are anchors, items that act are
+ * buttons. Neither gets a menu role.
+ *
+ * `disabled` uses whichever real mechanism the element has — the `disabled` attribute on a button,
+ * `aria-disabled` plus a suppressed activation on a link, since an anchor has no disabled attribute
+ * and one that merely looks unavailable but still navigates is a trap.
+ *
+ * `tone="danger"` is a visual cue only. A destructive action still needs its own confirmation step;
+ * colour is not a safeguard.
+ */
+export const DropdownItem = forwardRef(function DropdownItem({ href, tone = 'default', icon, children, disabled = false, className, ...rest }, ref) {
+    const shared = {
+        className: className === undefined ? 'lutra-dropdown__item' : `lutra-dropdown__item ${className}`,
+        'data-tone': tone,
+    };
+    // Rendered as real JSX children rather than passed through the shared spread, so the element
+    // visibly has content — both to a reader and to `jsx-a11y/anchor-has-content`.
+    const body = (_jsxs(_Fragment, { children: [icon !== undefined && icon !== null && (_jsx("span", { className: "lutra-dropdown__item-icon", "aria-hidden": "true", children: icon })), _jsx("span", { className: "lutra-dropdown__item-label", children: children })] }));
+    if (href !== undefined) {
+        const anchorProps = rest;
+        return (_jsx("a", { ...anchorProps, ...shared, ref: ref, href: href, "aria-disabled": disabled || undefined, onClick: (event) => {
+                // An anchor has no disabled attribute, so activation is suppressed by hand. Without this
+                // an item that looks unavailable would still navigate.
+                if (disabled) {
+                    event.preventDefault();
+                    return;
+                }
+                anchorProps.onClick?.(event);
+            }, children: body }));
+    }
+    const buttonProps = rest;
+    return (_jsx("button", { ...buttonProps, ...shared, ref: ref, type: "button", disabled: disabled, children: body }));
+});
+/** A visual divider between groups of items. Presentational only. */
+export function DropdownSeparator({ className }) {
+    return (_jsx("hr", { className: className === undefined
+            ? 'lutra-dropdown__separator'
+            : `lutra-dropdown__separator ${className}` }));
+}
+//# sourceMappingURL=dropdown.js.map

package/dist/components/dropdown/dropdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropdown.js","sourceRoot":"","sources":["../../../src/components/dropdown/dropdown.tsx"],"names":[],"mappings":"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"}

package/dist/components/dropdown/index.d.ts

@@ -0,0 +1,3 @@
+export { Dropdown, DropdownItem, DropdownSeparator } from './dropdown.js';
+export type { DropdownProps, DropdownItemProps } from './dropdown.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/dropdown/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/dropdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/components/dropdown/index.js

@@ -0,0 +1,2 @@
+export { Dropdown, DropdownItem, DropdownSeparator } from './dropdown.js';
+//# sourceMappingURL=index.js.map

package/dist/components/dropdown/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/dropdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/components/error-summary/error-summary.d.ts

@@ -0,0 +1,81 @@
+import type { HTMLAttributes } from 'react';
+export interface ErrorSummaryItem {
+    /**
+     * The `id` of the control this message belongs to. The entry links to it, and activating the entry
+     * moves focus there.
+     *
+     * The control needs an explicit `id` for this to work — pass the same one to `Field`, `Select
+     * Field` or `FieldGroup`.
+     */
+    fieldId: string;
+    /**
+     * The message, **word for word the same as the field's own inline error**. Two wordings for one
+     * problem reads as two problems.
+     */
+    message: string;
+}
+export interface ErrorSummaryProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** One entry per invalid field, in the order the fields appear in the form. */
+    errors: ErrorSummaryItem[];
+    /** @default 'There is a problem' */
+    title?: string;
+    /**
+     * Whether to take focus when the summary appears.
+     *
+     * On by default, because that is the whole point of the component: a summary nobody is sent to is
+     * a summary nobody reads. Turn it off only if you are managing focus yourself.
+     *
+     * Named `focusOnMount` rather than `autoFocus` on purpose. The native `autoFocus` attribute is a
+     * different mechanism with a deservedly bad reputation — it fires on page load, before anyone has
+     * asked for anything. This fires when a submit has already failed, which is the opposite
+     * situation, and the distinct name keeps the two from being read as the same thing.
+     *
+     * @default true
+     */
+    focusOnMount?: boolean;
+    /**
+     * Replaces `document.title` while the summary is mounted, restoring the previous title when it
+     * unmounts.
+     *
+     * **Opt-in**, and the contract asks for it: someone who navigated away and came back learns from
+     * the title alone that the submit failed. It is not automatic because a library silently rewriting
+     * the page title would be a surprise, and because the wording belongs to the application —
+     * `"Error: Apply for support"` reads better than anything this component could compose.
+     */
+    documentTitle?: string;
+}
+/**
+ * The list of everything that went wrong, shown above the form after a failed submit — and only
+ * then.
+ *
+ * ## What it is for
+ *
+ * A long form that fails validation leaves someone with no idea how many problems there are or where
+ * they live. The summary answers both at the top of the page, and every entry is a link to the field
+ * it names, so the answer comes with a way to act on it.
+ *
+ * **It never replaces inline errors.** The field keeps its own message, its `aria-invalid` and its
+ * `aria-describedby`; the summary is a second, earlier route to the same information. And the entry
+ * text must match the inline message word for word — two wordings for one problem reads as two
+ * problems.
+ *
+ * ## Focus
+ *
+ * The container is focusable **programmatically only** — `tabIndex={-1}`, so it never joins the tab
+ * order — and takes focus when it appears. That is what announces the failure immediately rather
+ * than leaving it to be discovered.
+ *
+ * It focuses on mount. A second failed submit while the summary is already on screen will not
+ * re-announce by itself: give it a `key` that changes per submission, or call `.focus()` on the ref.
+ * Both are shown in the stories.
+ *
+ * There is no `role="alert"` and no live region. Focus moving into the container is what announces
+ * it; a live region as well would say the same thing twice, and out of order.
+ *
+ * ## What it is not
+ *
+ * Not a form framework. It takes a list of errors you already have and renders it — validation, when
+ * to run it, and what the messages say are all yours.
+ */
+export declare const ErrorSummary: import("react").ForwardRefExoticComponent<ErrorSummaryProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=error-summary.d.ts.map

package/dist/components/error-summary/error-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-summary.d.ts","sourceRoot":"","sources":["../../../src/components/error-summary/error-summary.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,OAAO,CAAC;AAIxD,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACzF,+EAA+E;IAC/E,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY,8GAoFvB,CAAC"}

package/dist/components/error-summary/error-summary.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from '../../internal/isomorphic-layout-effect.js';
+function AlertCircleIcon() {
+    return (_jsxs("svg", { className: "lutra-error-summary__icon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", "aria-hidden": "true", focusable: "false", children: [_jsx("circle", { cx: "12", cy: "12", r: "10" }), _jsx("path", { d: "M12 7v6", strokeLinecap: "round" }), _jsx("path", { d: "M12 16.5h.01", strokeLinecap: "round" })] }));
+}
+/**
+ * The list of everything that went wrong, shown above the form after a failed submit — and only
+ * then.
+ *
+ * ## What it is for
+ *
+ * A long form that fails validation leaves someone with no idea how many problems there are or where
+ * they live. The summary answers both at the top of the page, and every entry is a link to the field
+ * it names, so the answer comes with a way to act on it.
+ *
+ * **It never replaces inline errors.** The field keeps its own message, its `aria-invalid` and its
+ * `aria-describedby`; the summary is a second, earlier route to the same information. And the entry
+ * text must match the inline message word for word — two wordings for one problem reads as two
+ * problems.
+ *
+ * ## Focus
+ *
+ * The container is focusable **programmatically only** — `tabIndex={-1}`, so it never joins the tab
+ * order — and takes focus when it appears. That is what announces the failure immediately rather
+ * than leaving it to be discovered.
+ *
+ * It focuses on mount. A second failed submit while the summary is already on screen will not
+ * re-announce by itself: give it a `key` that changes per submission, or call `.focus()` on the ref.
+ * Both are shown in the stories.
+ *
+ * There is no `role="alert"` and no live region. Focus moving into the container is what announces
+ * it; a live region as well would say the same thing twice, and out of order.
+ *
+ * ## What it is not
+ *
+ * Not a form framework. It takes a list of errors you already have and renders it — validation, when
+ * to run it, and what the messages say are all yours.
+ */
+export const ErrorSummary = forwardRef(function ErrorSummary({ errors, title = 'There is a problem', focusOnMount = true, documentTitle, className, ...nativeProps }, forwardedRef) {
+    const containerRef = useRef(null);
+    const setRef = (element) => {
+        containerRef.current = element;
+        if (typeof forwardedRef === 'function')
+            forwardedRef(element);
+        else if (forwardedRef)
+            forwardedRef.current = element;
+    };
+    // Before paint, so the summary is focused in the same frame it appears rather than a frame later,
+    // which a screen reader can otherwise miss.
+    useIsomorphicLayoutEffect(() => {
+        if (focusOnMount)
+            containerRef.current?.focus();
+        // Deliberately on mount only, and the empty dependency list is the point: re-running whenever
+        // `errors` changed would steal focus from someone who is mid-correction, which is the opposite
+        // of helping. A second failed submit re-announces through a new `key` or the forwarded ref.
+    }, []);
+    useEffect(() => {
+        if (documentTitle === undefined)
+            return;
+        const previous = document.title;
+        document.title = documentTitle;
+        return () => {
+            document.title = previous;
+        };
+    }, [documentTitle]);
+    const onEntryClick = (fieldId) => (event) => {
+        const target = document.getElementById(fieldId);
+        if (!target)
+            return;
+        // The anchor is real and its href works on its own — this only makes the landing better. A
+        // fragment link moves focus natively when the target is focusable, and does nothing useful when
+        // it is a wrapper, so focus is placed explicitly.
+        //
+        // `focus()` scrolls the element into view by itself, so there is no `scrollIntoView()` here:
+        // calling it as well would be a second scroll doing the same job, and one more browser API to
+        // feature-detect for no gain.
+        event.preventDefault();
+        target.focus();
+    };
+    return (_jsxs("div", { ...nativeProps, ref: setRef, className: className === undefined ? 'lutra-error-summary' : `lutra-error-summary ${className}`, 
+        // Focusable on purpose, in the tab order never.
+        tabIndex: -1, children: [_jsxs("div", { className: "lutra-error-summary__heading-row", children: [_jsx(AlertCircleIcon, {}), _jsx("h2", { className: "lutra-error-summary__title", children: title })] }), _jsx("ul", { className: "lutra-error-summary__list", children: errors.map((error) => (_jsx("li", { className: "lutra-error-summary__item", children: _jsx("a", { className: "lutra-error-summary__link", href: `#${error.fieldId}`, onClick: onEntryClick(error.fieldId), children: error.message }) }, error.fieldId))) })] }));
+});
+//# sourceMappingURL=error-summary.js.map

package/dist/components/error-summary/error-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-summary.js","sourceRoot":"","sources":["../../../src/components/error-summary/error-summary.tsx"],"names":[],"mappings":"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"}

package/dist/components/error-summary/index.d.ts

@@ -0,0 +1,3 @@
+export { ErrorSummary } from './error-summary.js';
+export type { ErrorSummaryProps, ErrorSummaryItem } from './error-summary.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/error-summary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/error-summary/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/components/error-summary/index.js

@@ -0,0 +1,2 @@
+export { ErrorSummary } from './error-summary.js';
+//# sourceMappingURL=index.js.map

package/dist/components/error-summary/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/error-summary/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/components/field/field.d.ts

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+import type { FieldIndicator } from '../../internal/field-support.js';
+import type { InputProps } from '../input/index.js';
+export type { FieldIndicator };
+/**
+ * Input props that Field derives rather than forwards.
+ *
+ * `invalid` is derived from `error`, and `aria-invalid` was never on `InputProps` to begin with, so
+ * the field's look, its announced state and its visible message all come from the one value.
+ */
+type ForwardedInputProps = Omit<InputProps, 'invalid'>;
+export interface FieldProps extends ForwardedInputProps {
+    /**
+     * The visible label. Always required — a field without one is not usable, and a placeholder is
+     * not a substitute for it.
+     */
+    label: ReactNode;
+    /**
+     * Supporting text shown above the control and connected with `aria-describedby`. Use it for
+     * format guidance the person needs before they start typing.
+     */
+    hint?: ReactNode;
+    /**
+     * The error message. **Its presence is what puts the field in the error state** — it drives the
+     * red treatment, `aria-invalid` on the control, and the visible message together, so they cannot
+     * disagree. Omit it and the field is valid.
+     */
+    error?: ReactNode;
+    /**
+     * The word shown after the label text and included in the accessible name.
+     *
+     * Defaults to `'required'` when the native `required` attribute is set, and `'none'` otherwise,
+     * so the visible word and the announced state agree by default. Pass `'optional'` to mark
+     * optional fields in a form where most are required.
+     */
+    indicator?: FieldIndicator;
+    /** Extra class on the field wrapper, not on the control. */
+    className?: string;
+}
+/**
+ * A labelled text field: label, optional hint, an `Input`, and an optional error message.
+ *
+ * This is the ordinary way to render an Input. The primitive deliberately does not manufacture a
+ * label; Field is what supplies one, associates it with `for`/`id`, and wires the hint and error to
+ * the control with `aria-describedby`.
+ *
+ * Everything not listed above is forwarded to the underlying `Input`, so `type`, `name`, `value`,
+ * `placeholder`, `required`, `readOnly`, `autoComplete`, `size`, `fullWidth`, the event handlers and
+ * `data-*` all behave exactly as they do there. A `ref` reaches the native `<input>`.
+ *
+ * Order is label → hint → control → error. The hint is above the control so it is read before the
+ * control is operated; the error is below it, matching the Figma annotation and Field Group.
+ */
+export declare const Field: import("react").ForwardRefExoticComponent<FieldProps & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=field.d.ts.map

package/dist/components/field/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,yGA4ChB,CAAC"}

package/dist/components/field/field.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { FieldShell, useFieldIds } from '../../internal/field-support.js';
+import { Input } from '../input/index.js';
+/**
+ * A labelled text field: label, optional hint, an `Input`, and an optional error message.
+ *
+ * This is the ordinary way to render an Input. The primitive deliberately does not manufacture a
+ * label; Field is what supplies one, associates it with `for`/`id`, and wires the hint and error to
+ * the control with `aria-describedby`.
+ *
+ * Everything not listed above is forwarded to the underlying `Input`, so `type`, `name`, `value`,
+ * `placeholder`, `required`, `readOnly`, `autoComplete`, `size`, `fullWidth`, the event handlers and
+ * `data-*` all behave exactly as they do there. A `ref` reaches the native `<input>`.
+ *
+ * Order is label → hint → control → error. The hint is above the control so it is read before the
+ * control is operated; the error is below it, matching the Figma annotation and Field Group.
+ */
+export const Field = forwardRef(function Field({ label, hint, error, indicator, className, id, required = false, disabled = false, 'aria-describedby': describedBy, ...inputProps }, ref) {
+    const hasHint = hint !== undefined && hint !== null && hint !== false;
+    const hasError = error !== undefined && error !== null && error !== false;
+    const ids = useFieldIds({ id, hasHint, hasError, describedBy });
+    const resolvedIndicator = indicator ?? (required ? 'required' : 'none');
+    return (_jsx(FieldShell, { controlId: ids.controlId, label: label, indicator: resolvedIndicator, hint: hint, hintId: ids.hintId, error: error, errorId: ids.errorId, disabled: disabled, className: className, children: _jsx(Input, { ...inputProps, ref: ref, id: ids.controlId, required: required, disabled: disabled, invalid: hasError, "aria-describedby": ids.describedBy }) }));
+});
+//# sourceMappingURL=field.js.map

package/dist/components/field/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AA0C1C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAA+B,SAAS,KAAK,CAC1E,EACE,KAAK,EACL,IAAI,EACJ,KAAK,EACL,SAAS,EACT,SAAS,EACT,EAAE,EACF,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,EAC/B,GAAG,UAAU,EACd,EACD,GAAG;IAEH,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAmB,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExF,OAAO,CACL,KAAC,UAAU,IACT,SAAS,EAAE,GAAG,CAAC,SAAS,EACxB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,YAEpB,KAAC,KAAK,OACA,UAAU,EACd,GAAG,EAAE,GAAG,EACR,EAAE,EAAE,GAAG,CAAC,SAAS,EACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,QAAQ,sBACC,GAAG,CAAC,WAAW,GACjC,GACS,CACd,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/components/field/index.d.ts

@@ -0,0 +1,3 @@
+export { Field } from './field.js';
+export type { FieldProps, FieldIndicator } from './field.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/field/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/field/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/field/index.js

@@ -0,0 +1,2 @@
+export { Field } from './field.js';
+//# sourceMappingURL=index.js.map

package/dist/components/field/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/field/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/field-group/field-group.d.ts

@@ -0,0 +1,67 @@
+import type { FieldsetHTMLAttributes, ReactNode } from 'react';
+/**
+ * Native `<fieldset>` attributes, minus what this component owns.
+ *
+ * `FieldsetHTMLAttributes` rather than the generic `HTMLAttributes`, so the element's own
+ * attributes survive the wrapper: `name` and `form` are specific to `<fieldset>` and would be
+ * dropped by the generic type. `disabled` belongs to it too, and is redeclared below only so it can
+ * carry documentation and a default.
+ */
+type NativeFieldsetProps = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, 'children' | 'disabled'>;
+export interface FieldGroupProps extends NativeFieldsetProps {
+    /**
+     * The question the controls answer, rendered as a `<legend>`.
+     *
+     * The legend provides the accessible name for the group, and is the context an assistive
+     * technology has available while a user moves through the controls inside it. Keep it short:
+     * assistive technologies may expose that context repeatedly as the controls are navigated.
+     */
+    legend: ReactNode;
+    /**
+     * Instructions or supporting text for the group, connected with `aria-describedby`.
+     *
+     * **There is no default.** "Choose all that apply" is right for a checkbox group and wrong for a
+     * radio group, and a generic default would be wrong roughly half the time — which is why the
+     * design master removed it. Say what this particular question needs.
+     */
+    hint?: ReactNode;
+    /**
+     * The error message for the group. Its presence is what puts the group in the error state, so the
+     * red treatment and the visible message cannot disagree.
+     *
+     * A group-level failure is the normal case for radios and checkboxes: the question was not
+     * answered, rather than one option being wrong.
+     */
+    error?: ReactNode;
+    /** Whether the group is disabled. Native — it disables every control inside. */
+    disabled?: boolean;
+    /** The controls: `CheckboxItem`s, `RadioItem`s, or anything else the question needs. */
+    children: ReactNode;
+}
+/**
+ * A group of related controls that answer one question.
+ *
+ * Renders a native `<fieldset>` with a `<legend>`, which is the platform's own grouping semantic:
+ * the legend names the group, and `disabled` on the fieldset disables every control in it. Neither
+ * is reimplemented, and neither needs ARIA to replace it.
+ *
+ * Order is legend → hint → controls → error, matching `Field`.
+ *
+ * ## Why there is no `role="group"` or `aria-invalid` here
+ *
+ * `<fieldset>` already carries the group semantic, so adding `role="group"` would restate what the
+ * element says. `aria-invalid` is not placed on the fieldset either: it is defined for widgets that
+ * hold a value, and a fieldset holds none — assistive technology would have nothing to attach it to.
+ *
+ * The group's invalid state is therefore expressed as a relationship rather than a state flag: the
+ * error message is connected to the `<fieldset>` with `aria-describedby`, which is the established
+ * way to attach supporting text to a group, and the individual controls draw their own error
+ * treatment through their `invalid` prop. Exactly how and when a given screen reader surfaces a
+ * group-level description varies, and this component does not promise any particular behaviour —
+ * which is why the message is also visible on screen and the controls are drawn in their error
+ * state. That is the accessibility annotation's model, and it is why `Radio`'s `invalid` is visual
+ * only.
+ */
+export declare function FieldGroup({ legend, hint, error, disabled, className, children, 'aria-describedby': describedBy, ...nativeProps }: FieldGroupProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=field-group.d.ts.map

package/dist/components/field-group/field-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-group.d.ts","sourceRoot":"","sources":["../../../src/components/field-group/field-group.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/D;;;;;;;GAOG;AACH,KAAK,mBAAmB,GAAG,IAAI,CAC7B,sBAAsB,CAAC,mBAAmB,CAAC,EAC3C,UAAU,GAAG,UAAU,CACxB,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wFAAwF;IACxF,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,IAAI,EACJ,KAAK,EACL,QAAgB,EAChB,SAAS,EACT,QAAQ,EACR,kBAAkB,EAAE,WAAW,EAC/B,GAAG,WAAW,EACf,EAAE,eAAe,+BAmDjB"}

package/dist/components/field-group/field-group.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+/**
+ * A group of related controls that answer one question.
+ *
+ * Renders a native `<fieldset>` with a `<legend>`, which is the platform's own grouping semantic:
+ * the legend names the group, and `disabled` on the fieldset disables every control in it. Neither
+ * is reimplemented, and neither needs ARIA to replace it.
+ *
+ * Order is legend → hint → controls → error, matching `Field`.
+ *
+ * ## Why there is no `role="group"` or `aria-invalid` here
+ *
+ * `<fieldset>` already carries the group semantic, so adding `role="group"` would restate what the
+ * element says. `aria-invalid` is not placed on the fieldset either: it is defined for widgets that
+ * hold a value, and a fieldset holds none — assistive technology would have nothing to attach it to.
+ *
+ * The group's invalid state is therefore expressed as a relationship rather than a state flag: the
+ * error message is connected to the `<fieldset>` with `aria-describedby`, which is the established
+ * way to attach supporting text to a group, and the individual controls draw their own error
+ * treatment through their `invalid` prop. Exactly how and when a given screen reader surfaces a
+ * group-level description varies, and this component does not promise any particular behaviour —
+ * which is why the message is also visible on screen and the controls are drawn in their error
+ * state. That is the accessibility annotation's model, and it is why `Radio`'s `invalid` is visual
+ * only.
+ */
+export function FieldGroup({ legend, hint, error, disabled = false, className, children, 'aria-describedby': describedBy, ...nativeProps }) {
+    const generated = useId();
+    const base = `lutra-field-group-${generated}`;
+    const hasHint = hint !== undefined && hint !== null && hint !== false;
+    const hasError = error !== undefined && error !== null && error !== false;
+    const hintId = hasHint ? `${base}-hint` : undefined;
+    const errorId = hasError ? `${base}-error` : undefined;
+    // The consumer's own description is preserved and listed first, as it is in Field.
+    const parts = [describedBy, hintId, errorId].filter((part) => Boolean(part));
+    return (_jsxs("fieldset", { ...nativeProps, className: className === undefined ? 'lutra-field-group' : `lutra-field-group ${className}`, disabled: disabled, "aria-describedby": parts.length > 0 ? parts.join(' ') : undefined, "data-invalid": hasError ? 'true' : undefined, children: [_jsx("legend", { className: "lutra-field-group__legend", children: legend }), hasHint && (_jsx("p", { className: "lutra-field-group__hint", id: hintId, children: hint })), _jsx("div", { className: "lutra-field-group__items", children: children }), hasError && (_jsxs("p", { className: "lutra-field-group__error", id: errorId, children: [_jsxs("svg", { className: "lutra-field-group__error-icon", viewBox: "0 0 16 16", "aria-hidden": "true", focusable: "false", children: [_jsx("circle", { cx: "8", cy: "8", r: "7", fill: "none", stroke: "currentColor", strokeWidth: "1.5" }), _jsx("path", { d: "M8 4.5v4.25", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round" }), _jsx("circle", { cx: "8", cy: "11.5", r: "0.9", fill: "currentColor" })] }), error] }))] }));
+}
+//# sourceMappingURL=field-group.js.map

package/dist/components/field-group/field-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-group.js","sourceRoot":"","sources":["../../../src/components/field-group/field-group.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AA+C9B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,EACzB,MAAM,EACN,IAAI,EACJ,KAAK,EACL,QAAQ,GAAG,KAAK,EAChB,SAAS,EACT,QAAQ,EACR,kBAAkB,EAAE,WAAW,EAC/B,GAAG,WAAW,EACE;IAChB,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,qBAAqB,SAAS,EAAE,CAAC;IAE9C,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAEvD,mFAAmF;IACnF,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7F,OAAO,CACL,uBACM,WAAW,EACf,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,qBAAqB,SAAS,EAAE,EAC3F,QAAQ,EAAE,QAAQ,sBACA,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,kBAClD,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,aAE3C,iBAAQ,SAAS,EAAC,2BAA2B,YAAE,MAAM,GAAU,EAE9D,OAAO,IAAI,CACV,YAAG,SAAS,EAAC,yBAAyB,EAAC,EAAE,EAAE,MAAM,YAC9C,IAAI,GACH,CACL,EAED,cAAK,SAAS,EAAC,0BAA0B,YAAE,QAAQ,GAAO,EAEzD,QAAQ,IAAI,CACX,aAAG,SAAS,EAAC,0BAA0B,EAAC,EAAE,EAAE,OAAO,aAIjD,eACE,SAAS,EAAC,+BAA+B,EACzC,OAAO,EAAC,WAAW,iBACP,MAAM,EAClB,SAAS,EAAC,OAAO,aAEjB,iBAAQ,EAAE,EAAC,GAAG,EAAC,EAAE,EAAC,GAAG,EAAC,CAAC,EAAC,GAAG,EAAC,IAAI,EAAC,MAAM,EAAC,MAAM,EAAC,cAAc,EAAC,WAAW,EAAC,KAAK,GAAG,EAClF,eAAM,CAAC,EAAC,aAAa,EAAC,MAAM,EAAC,cAAc,EAAC,WAAW,EAAC,KAAK,EAAC,aAAa,EAAC,OAAO,GAAG,EACtF,iBAAQ,EAAE,EAAC,GAAG,EAAC,EAAE,EAAC,MAAM,EAAC,CAAC,EAAC,KAAK,EAAC,IAAI,EAAC,cAAc,GAAG,IACnD,EACL,KAAK,IACJ,CACL,IACQ,CACZ,CAAC;AACJ,CAAC"}