pne-ui 4.3.0-rc.13 → 4.3.0-rc.14

package/README.md

@@ -49,6 +49,79 @@ major-версии MUI не входят в поддерживаемый peer co
 Компонент сохраняет polymorphic MUI-контракт для `component` и `href`; типы DOM props, событий и `ref`
 выводятся из фактического root element. Это поведение рассчитано на React 19 ref-as-prop.
 
+`PneButtonGroup` удалён из публичного API. Для группировки используйте `ButtonGroup` напрямую из
+`@mui/material`; расстояние между независимыми действиями задавайте на layout-контейнере.
+
+## PneField
+
+`PneField` задаёт общий семантический контракт для одного поля: label, helper text, error/disabled/required state и
+их ARIA-связи с единственным логическим control или control group. `PneTextField`, `PneSelect`,
+`PneAutocomplete`, `PneAsyncAutocomplete`, `PneCheckbox` и `PneSwitch` читают этот контракт автоматически.
+Внутри `PneField` должен быть ровно один логический control; для группы передавайте один group component, а не
+несколько соседних controls. `PneField` не принимает ID произвольной layout-обёртки за ID самого control.
+
+`id` принадлежит root `FormControl` и служит namespace для сгенерированных ID. `controlId` принадлежит самому
+интерактивному control и используется в `label[for]`; эти ID должны различаться. Указанный на child `id` не
+переопределяет field-owned ID, поэтому при миграции переносите его в `controlId`. Prop `htmlFor` оставлен только
+как deprecated alias `controlId` и не должен использоваться в новом коде. ID обрезаются по краям; пустые ID и
+ID с внутренними пробельными символами считаются невалидными, игнорируются и заменяются сгенерированными.
+
+```tsx
+<PneField
+    id="delivery-field"
+    controlId="delivery-control"
+    label="Delivery server"
+    helperText="Select one server"
+    slotProps={{
+        label: {id: "delivery-label", "data-autotest": "delivery-label"},
+        helperText: {id: "delivery-help", "data-autotest": "delivery-help"},
+    }}
+>
+    <PneSelect options={servers} value={server} onChange={setServer}/>
+</PneField>
+```
+
+Для произвольного control используйте render prop и передайте результат `getControlProps` на фактический
+focusable control или group root. Adapter сохраняет дополнительные props, объединяет consumer
+`aria-labelledby`/`aria-describedby` с ID label/helper text и дедуплицирует ссылки. Явный `aria-label`
+остаётся самостоятельным naming override и не смешивается с `aria-labelledby`. При disabled field adapter
+возвращает одновременно `disabled` и `aria-disabled`; это сохраняет нативную/MUI блокировку и корректно
+описывает composite control с group-role.
+
+```tsx
+<PneField label="Period" helperText="Choose a unit" error={Boolean(error)} required>
+    {({getControlProps, fullWidth}) => (
+        <ToggleButtonGroup
+            {...getControlProps({"aria-describedby": "period-format"})}
+            exclusive
+            sx={{width: fullWidth ? "100%" : "auto"}}
+            value={period}
+            onChange={(_event, value) => setPeriod(value)}
+        >
+            <ToggleButton value="day">Day</ToggleButton>
+            <ToggleButton value="week">Week</ToggleButton>
+        </ToggleButtonGroup>
+    )}
+</PneField>
+```
+
+Если adapter нужен внутри отдельного descendant component, вызовите `usePneFieldControl()` там; вне
+`PneField` hook возвращает `undefined`. Render prop предпочтительнее для прямой композиции, потому что явно
+показывает место применения DOM-контракта.
+
+`PneField` владеет ID и связями label/helper text. Значения `true` у field-level `disabled`, `error` и
+`required` нельзя ослабить props дочернего control; его дополнительные ARIA ID при этом не теряются. Явный
+`fullWidth` у встроенного PNE control может переопределить field default. `required` на `PneField` добавляет
+asterisk и `aria-required`, но намеренно не устанавливает нативный `required`: browser constraint validation
+включается только `required` на самом input/select/checkbox/switch.
+
+`slotProps.label` и `slotProps.helperText` предназначены для `id`, `className`, `sx`, `ref`, ARIA и `data-*`
+соответствующих slots. Старые `labelSx` и `helperTextSx` deprecated. Split-state props MUI FormControl
+(`color`, `focused`, `hiddenLabel`, `size`, `variant`) не входят в публичный API `PneField`; внешний вид control
+настраивается на самом control, а label/helper — через `slotProps`. Root остаётся polymorphic через `component`,
+и тип `ref` выводится из выбранного root element. `margin` остаётся исключительно layout-prop root
+`FormControl` и не передаётся дочернему control.
+
 ## PneTextField
 
 `PneTextField` сохраняет API MUI `TextField` и по умолчанию использует `size="small"`. Его `ref` указывает на
@@ -106,6 +179,59 @@ ID helper text, сохраняет явный `helperTextProps.id` и объед
 </PneField>
 ```
 
+## PneModal и PneModalActions
+
+`PneModal` владеет структурой dialog, focus trap и ARIA-связями. Передайте видимый `title`; для модалок без
+визуального заголовка используйте `ariaLabel`. Если компонент внутри `title` сам возвращает `null`, передайте
+`title={null}` и `ariaLabel` явно: содержимое произвольного React-компонента нельзя определить до его рендера.
+`title` и `subtitle` принимают `ReactNode`. `ref` указывает на
+`HTMLDivElement` с `role="dialog"`. Структурные `role`, `aria-modal`, `aria-labelledby` и `aria-describedby`
+нельзя переопределить через container slot; дополнительное описание подключается через `ariaDescribedBy`.
+
+`onClose(event, reason)` различает `closeButtonClick`, `escapeKeyDown` и `backdropClick`. Существующие callbacks
+без аргументов остаются совместимыми. `closeLabel` необязателен и по умолчанию равен `Close`; передавайте перевод
+только там, где он доступен consumer-у. `hideCloseButton` скрывает icon button без дополнительных обязательных
+props.
+
+```tsx
+<PneModal
+    actions={<PneModalActions
+        secondary={<PneButton pneStyle="outlined">Cancel</PneButton>}
+        primary={<PneButton>Save</PneButton>}
+    />}
+    closeLabel="Close"
+    onClose={(_event, reason) => {
+        if (reason !== "backdropClick") setOpen(false)
+    }}
+    open={open}
+    title={<span>Edit account</span>}
+    slotProps={{
+        container: {"data-autotest": "account-dialog"},
+        title: {component: "h2"},
+    }}
+>
+    Account form
+</PneModal>
+```
+
+`blockingOverlay` предназначен для loading-состояния всей модалки. Пока slot присутствует, dialog получает
+`aria-busy`, header/body/footer становятся inert, focus остаётся на границе dialog, а Escape, backdrop и close
+button не вызывают `onClose`. После снятия overlay прежний focused control восстанавливается, если он всё ещё
+существует. Старый `overlay` оставлен как deprecated alias.
+
+Внутренние части настраиваются через `slotProps`, но их element type, owned content и dialog semantics остаются
+фиксированными. `modalProps` содержит только безопасные настройки MUI root и не позволяет подменять root/backdrop
+slots. Прежние `containerProps` и `closeButtonProps` оставлены deprecated на период миграции.
+
+Частые тестовые маркеры `data-*` передаются прямо в `PneModal` и попадают на семантический dialog container:
+`<PneModal data-testattribute="edit-modal" ... />`. Для них не требуется обёртка `slotProps.container`;
+этот slot остаётся для остальных безопасных атрибутов и `sx` контейнера.
+
+`PneModalActions` сохраняет одни и те же keyed action nodes, но синхронизирует DOM/focus order с layout:
+`leading → secondary → primary` на desktop и `primary → secondary → leading` на экране до 480 px. При смене
+breakpoint существующие controls только перемещаются внутри дерева, не перемонтируются и не теряют focus/state.
+Root фиксирован как `div`, поддерживает `ref`, `sx`, обычные HTML/ARIA/data attributes.
+
 ## PneSelect
 
 `PneSelect` — controlled single-select для произвольного типа option. `value` имеет тип `T | null`, а `onChange`

package/cjs/component/PneCheckbox.js

@@ -43,7 +43,9 @@ exports.PneCheckbox = (0, react_1.forwardRef)((props, ref) => {
         }
     }, [indeterminate]);
     const inputSlotProps = (0, PneToggleInput_1.composeToggleInputSlotProps)([defaultInputSlotProps, consumerInputSlotProps], {
+        controlId: controlProps.id ?? id,
         describedBy: controlProps.ariaDescribedBy,
+        forceDisabled: controlProps.disabled === true || disabled === true,
         forceInvalid: controlProps.error,
         forceRequired: controlProps.ariaRequired,
         inputAriaProps,

package/cjs/component/PneCheckbox.js.map

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

package/cjs/component/PneField.d.ts

@@ -1,18 +1,58 @@
-import React, { ReactNode } from 'react';
-import { FormControlProps, SxProps } from '@mui/material';
-import { Theme } from '@mui/material/styles';
-export interface PneFieldProps extends Omit<FormControlProps, 'children' | 'disabled' | 'error' | 'fullWidth' | 'required'> {
-    children: ReactNode;
+import type { FormControlTypeMap } from '@mui/material/FormControl';
+import type { FormHelperTextProps } from '@mui/material/FormHelperText';
+import type { FormLabelProps } from '@mui/material/FormLabel';
+import type { OverridableComponent, OverrideProps } from '@mui/material/OverridableComponent';
+import type { SxProps, Theme } from '@mui/material/styles';
+import * as React from 'react';
+import { type PneFieldControlAdapter } from './PneFieldContext';
+type PneFieldDataAttributes = {
+    [attribute: `data-${string}`]: string | number | boolean | undefined;
+};
+export type PneFieldLabelSlotProps = Omit<FormLabelProps, 'children' | 'component' | 'disabled' | 'error' | 'filled' | 'focused' | 'htmlFor' | 'required'> & {
+    ref?: React.Ref<HTMLLabelElement>;
+} & PneFieldDataAttributes;
+export type PneFieldHelperTextSlotProps = Omit<FormHelperTextProps, 'children' | 'component' | 'disabled' | 'error' | 'filled' | 'focused' | 'margin' | 'required' | 'variant'> & {
+    ref?: React.Ref<HTMLParagraphElement>;
+} & PneFieldDataAttributes;
+export interface PneFieldSlotProps {
+    helperText?: PneFieldHelperTextSlotProps;
+    label?: PneFieldLabelSlotProps;
+}
+export type PneFieldChildren = React.ReactElement | ((field: PneFieldControlAdapter) => React.ReactElement);
+type RemovedFormControlProp = 'children' | 'color' | 'disabled' | 'error' | 'focused' | 'fullWidth' | 'hiddenLabel' | 'required' | 'size' | 'variant';
+type PneFieldOwnProps = Omit<FormControlTypeMap['props'], RemovedFormControlProp> & {
+    children: PneFieldChildren;
+    /** ID owned by the primary control. `PneField` state always wins conflicting child IDs. */
+    controlId?: string;
     disabled?: boolean;
     error?: boolean;
     fullWidth?: boolean;
-    helperText?: ReactNode;
+    helperText?: React.ReactNode;
+    /** @deprecated Use `slotProps.helperText.sx`. */
     helperTextSx?: SxProps<Theme>;
+    /** @deprecated Use `controlId`; kept as a compatibility alias. */
     htmlFor?: string;
+    /** ID of the field root and namespace for generated label/helper/control IDs. */
     id?: string;
-    label?: ReactNode;
+    label?: React.ReactNode;
+    /** @deprecated Use `slotProps.label.sx`. */
     labelSx?: SxProps<Theme>;
     required?: boolean;
-}
-declare const PneField: React.ForwardRefExoticComponent<Omit<PneFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+    slotProps?: PneFieldSlotProps;
+    /** Split FormControl appearance state is intentionally not part of the field contract. */
+    color?: never;
+    focused?: never;
+    hiddenLabel?: never;
+    size?: never;
+    variant?: never;
+};
+type PneFieldTypeMap<AdditionalProps = {}, RootComponent extends React.ElementType = 'div'> = {
+    props: PneFieldOwnProps & AdditionalProps;
+    defaultComponent: RootComponent;
+};
+export type PneFieldProps<RootComponent extends React.ElementType = 'div', AdditionalProps = {}> = OverrideProps<PneFieldTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
+    component?: RootComponent;
+};
+type PneFieldComponent = OverridableComponent<PneFieldTypeMap>;
+declare const PneField: PneFieldComponent;
 export default PneField;

package/cjs/component/PneField.js

@@ -1,34 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-const react_1 = tslib_1.__importStar(require("react"));
 const material_1 = require("@mui/material");
+const React = tslib_1.__importStar(require("react"));
 const PneFieldContext_1 = require("./PneFieldContext");
-const PneField = (0, react_1.forwardRef)((props, ref) => {
-    const { children, disabled = false, error = false, fullWidth = true, helperText, helperTextSx, htmlFor, id, label, labelSx, required = false, sx, ...rest } = props;
-    const generatedId = (0, react_1.useId)();
-    const fieldId = id ?? generatedId;
-    const childId = getChildId(children);
-    const controlId = htmlFor ?? childId ?? `${fieldId}-control`;
-    const helperTextId = helperText ? `${fieldId}-helper-text` : undefined;
-    const labelId = label ? `${fieldId}-label` : undefined;
-    const contextValue = {
+const PneFieldImplementation = (props) => {
+    const { children, controlId: controlIdProp, disabled = false, error = false, fullWidth = true, helperText, helperTextSx, htmlFor, id, label, labelSx, required = false, slotProps, sx, ...rest } = props;
+    const generatedId = React.useId();
+    const rootId = normalizeId(id);
+    const fieldId = rootId ?? generatedId;
+    const explicitControlId = normalizeId(controlIdProp);
+    const legacyControlId = normalizeId(htmlFor);
+    const controlId = explicitControlId ?? legacyControlId ?? `${fieldId}-control`;
+    const hasLabel = hasRenderableContent(label);
+    const hasHelperText = hasRenderableContent(helperText);
+    const labelSlotId = normalizeId(slotProps?.label?.id);
+    const helperTextSlotId = normalizeId(slotProps?.helperText?.id);
+    const labelId = hasLabel ? labelSlotId ?? `${fieldId}-label` : undefined;
+    const helperTextId = hasHelperText
+        ? helperTextSlotId ?? `${fieldId}-helper-text`
+        : undefined;
+    warnAboutFieldIdConflicts({
+        controlId,
+        controlIdProp: explicitControlId,
+        htmlFor: legacyControlId,
+        rootId,
+    });
+    const adapter = React.useMemo(() => ({
         controlId,
         disabled,
         error,
         fullWidth,
+        getControlProps: (controlProps) => {
+            const ownProps = controlProps
+                ?? {};
+            const ownId = normalizeId(ownProps.id);
+            if (process.env.NODE_ENV !== 'production' && ownId && ownId !== controlId) {
+                console.warn(`PneField owns control ID "${controlId}" and ignores conflicting child ID "${ownId}". `
+                    + 'Move the ID to PneField controlId.');
+            }
+            return {
+                ...ownProps,
+                'aria-describedby': (0, PneFieldContext_1.mergeAriaIds)(ownProps['aria-describedby'], helperTextId),
+                'aria-disabled': disabled || ownProps.disabled === true
+                    ? true
+                    : ownProps['aria-disabled'],
+                'aria-invalid': error ? true : ownProps['aria-invalid'],
+                'aria-labelledby': hasAriaLabel(ownProps['aria-label'])
+                    ? undefined
+                    : (0, PneFieldContext_1.mergeAriaIds)(labelId, ownProps['aria-labelledby']),
+                'aria-required': required ? true : ownProps['aria-required'],
+                disabled: disabled || ownProps.disabled === true,
+                id: controlId,
+            };
+        },
         helperTextId,
         labelId,
         required,
-    };
-    return react_1.default.createElement(material_1.FormControl, { disabled: disabled, error: error, fullWidth: fullWidth, id: id, required: required, ref: ref, sx: [
+    }), [controlId, disabled, error, fullWidth, helperTextId, labelId, required]);
+    const resolvedChildren = typeof children === 'function' ? children(adapter) : children;
+    validateChildren(resolvedChildren, hasLabel);
+    const { id: _labelId, ref: labelRef, sx: labelSlotSx, ...labelSlotProps } = slotProps?.label ?? {};
+    const { id: _helperTextId, ref: helperTextRef, sx: helperTextSlotSx, ...helperTextSlotProps } = slotProps?.helperText ?? {};
+    return React.createElement(material_1.FormControl, { disabled: disabled, error: error, fullWidth: fullWidth, id: rootId, required: required, sx: [
             {
                 gap: '4px',
             },
             ...(Array.isArray(sx) ? sx : [sx]),
         ], ...rest },
-        label
-            ? react_1.default.createElement(material_1.FormLabel, { htmlFor: controlId, id: labelId, required: required, sx: [
+        hasLabel
+            ? React.createElement(material_1.FormLabel, { ...labelSlotProps, htmlFor: controlId, id: labelId, ref: labelRef, required: required, sx: [
                     {
                         alignSelf: 'flex-start',
                         color: error ? 'error.main' : 'text.secondary',
@@ -43,25 +84,69 @@ const PneField = (0, react_1.forwardRef)((props, ref) => {
                         },
                     },
                     ...(Array.isArray(labelSx) ? labelSx : [labelSx]),
+                    ...(Array.isArray(labelSlotSx) ? labelSlotSx : [labelSlotSx]),
                 ] }, label)
             : null,
-        react_1.default.createElement(PneFieldContext_1.PneFieldContext.Provider, { value: contextValue }, children),
-        helperText
-            ? react_1.default.createElement(material_1.FormHelperText, { id: helperTextId, sx: [
+        React.createElement(PneFieldContext_1.PneFieldContext.Provider, { value: adapter }, resolvedChildren),
+        hasHelperText
+            ? React.createElement(material_1.FormHelperText, { ...helperTextSlotProps, id: helperTextId, ref: helperTextRef, sx: [
                     {
                         mx: '14px',
                     },
                     ...(Array.isArray(helperTextSx) ? helperTextSx : [helperTextSx]),
+                    ...(Array.isArray(helperTextSlotSx) ? helperTextSlotSx : [helperTextSlotSx]),
                 ] }, helperText)
             : null);
-});
-const getChildId = (children) => {
-    if (!(0, react_1.isValidElement)(children)) {
+};
+const normalizeId = (value) => {
+    if (typeof value !== 'string') {
         return undefined;
     }
-    return typeof children.props.id === 'string' && children.props.id !== ''
-        ? children.props.id
-        : undefined;
+    const normalized = value.trim();
+    if (normalized === '') {
+        return undefined;
+    }
+    if (/\s/.test(normalized)) {
+        if (process.env.NODE_ENV !== 'production') {
+            console.warn(`PneField ignores invalid ID containing whitespace: "${value}".`);
+        }
+        return undefined;
+    }
+    return normalized;
+};
+const hasRenderableContent = (value) => value !== undefined && value !== null && typeof value !== 'boolean' && value !== '';
+const hasAriaLabel = (value) => typeof value === 'string' && value.trim() !== '';
+const warnAboutFieldIdConflicts = (options) => {
+    if (process.env.NODE_ENV === 'production') {
+        return;
+    }
+    if (options.controlIdProp && options.htmlFor && options.controlIdProp !== options.htmlFor) {
+        console.warn(`PneField controlId "${options.controlIdProp}" overrides conflicting deprecated htmlFor `
+            + `"${options.htmlFor}".`);
+    }
+    if (options.rootId && options.rootId === options.controlId) {
+        console.warn(`PneField root ID and controlId are both "${options.rootId}". `
+            + 'Use distinct IDs to avoid duplicate DOM IDs.');
+    }
+};
+const validateChildren = (children, hasLabel) => {
+    const directChildren = React.isValidElement(children)
+        && children.type === React.Fragment
+        ? children.props.children
+        : children;
+    if (React.Children.count(directChildren) !== 1) {
+        throw new Error('PneField expects exactly one logical control or group.');
+    }
+    if (process.env.NODE_ENV === 'production') {
+        return;
+    }
+    if (hasLabel
+        && React.isValidElement(children)
+        && hasRenderableContent(children.props.label)) {
+        console.warn('PneField and its direct child both provide labels. Use one label owner to avoid an ambiguous accessible name.');
+    }
 };
+PneFieldImplementation.displayName = 'PneField';
+const PneField = PneFieldImplementation;
 exports.default = PneField;
 //# sourceMappingURL=PneField.js.map

package/cjs/component/PneField.js.map

@@ -1 +1 @@
-{"version":3,"file":"PneField.js","sourceRoot":"","sources":["../../src/component/PneField.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"PneField.js","sourceRoot":"","sources":["../../src/component/PneField.tsx"],"names":[],"mappings":";;;AAIA,4CAAoE;AAEpE,qDAA8B;AAC9B,uDAM0B;AAoG1B,MAAM,sBAAsB,GAAG,CAC3B,KAAwC,EAC1C,EAAE;IACA,MAAM,EACF,QAAQ,EACR,SAAS,EAAE,aAAa,EACxB,QAAQ,GAAG,KAAK,EAChB,KAAK,GAAG,KAAK,EACb,SAAS,GAAG,IAAI,EAChB,UAAU,EACV,YAAY,EACZ,OAAO,EACP,EAAE,EACF,KAAK,EACL,OAAO,EACP,QAAQ,GAAG,KAAK,EAChB,SAAS,EACT,EAAE,EACF,GAAG,IAAI,EACV,GAAG,KAAK,CAAA;IAET,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,CAAA;IACjC,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAA;IAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,WAAW,CAAA;IACrC,MAAM,iBAAiB,GAAG,WAAW,CAAC,aAAa,CAAC,CAAA;IACpD,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAC5C,MAAM,SAAS,GAAG,iBAAiB,IAAI,eAAe,IAAI,GAAG,OAAO,UAAU,CAAA;IAC9E,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;IAC5C,MAAM,aAAa,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAA;IACtD,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;IACrD,MAAM,gBAAgB,GAAG,WAAW,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,CAAA;IAC/D,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,WAAW,IAAI,GAAG,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;IACxE,MAAM,YAAY,GAAG,aAAa;QAC9B,CAAC,CAAC,gBAAgB,IAAI,GAAG,OAAO,cAAc;QAC9C,CAAC,CAAC,SAAS,CAAA;IAEf,yBAAyB,CAAC;QACtB,SAAS;QACT,aAAa,EAAE,iBAAiB;QAChC,OAAO,EAAE,eAAe;QACxB,MAAM;KACT,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAyB,GAAG,EAAE,CAAC,CAAC;QACzD,SAAS;QACT,QAAQ;QACR,KAAK;QACL,SAAS;QACT,eAAe,EAAE,CACb,YAAqD,EACvD,EAAE;YACA,MAAM,QAAQ,GAA2C,YAAY;mBAC9D,EAA4C,CAAA;YACnD,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YAEtC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,KAAK,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxE,OAAO,CAAC,IAAI,CACR,6BAA6B,SAAS,uCAAuC,KAAK,KAAK;sBACrF,oCAAoC,CACzC,CAAA;YACL,CAAC;YAED,OAAO;gBACH,GAAG,QAAQ;gBACX,kBAAkB,EAAE,IAAA,8BAAY,EAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAC5B,YAAY,CACf;gBACD,eAAe,EAAE,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI;oBACnD,CAAC,CAAC,IAAI;oBACN,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;gBAC/B,cAAc,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;gBACvD,iBAAiB,EAAE,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;oBACnD,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,IAAA,8BAAY,EAAC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;gBACxD,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;gBAC5D,QAAQ,EAAE,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI;gBAChD,EAAE,EAAE,SAAS;aAEoB,CAAA;QACzC,CAAC;QACD,YAAY;QACZ,OAAO;QACP,QAAQ;KACX,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE7E,MAAM,gBAAgB,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;IACtF,gBAAgB,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAA;IAE5C,MAAM,EACF,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,WAAW,EACf,GAAG,cAAc,EACpB,GAAG,SAAS,EAAE,KAAK,IAAI,EAAE,CAAA;IAC1B,MAAM,EACF,EAAE,EAAE,aAAa,EACjB,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,gBAAgB,EACpB,GAAG,mBAAmB,EACzB,GAAG,SAAS,EAAE,UAAU,IAAI,EAAE,CAAA;IAE/B,OAAO,oBAAC,sBAAW,IACf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE;YACA;gBACI,GAAG,EAAE,KAAK;aACb;YACD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACrC,KACG,IAAI;QAEP,QAAQ;YACL,CAAC,CAAC,oBAAC,oBAAS,OACJ,cAAc,EAClB,OAAO,EAAE,SAAS,EAClB,EAAE,EAAE,OAAO,EACX,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE;oBACA;wBACI,SAAS,EAAE,YAAY;wBACvB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB;wBAC9C,QAAQ,EAAE,UAAU;wBACpB,UAAU,EAAE,MAAM;wBAClB,QAAQ,EAAE,MAAM;wBAChB,eAAe,EAAE;4BACb,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB;yBACjD;wBACD,0BAA0B,EAAE;4BACxB,KAAK,EAAE,YAAY;yBACtB;qBACJ;oBACD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;oBACjD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;iBAChE,IAEA,KAAK,CACE;YACZ,CAAC,CAAC,IAAI;QACV,oBAAC,iCAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,IACnC,gBAAgB,CACM;QAC1B,aAAa;YACV,CAAC,CAAC,oBAAC,yBAAc,OACT,mBAAmB,EACvB,EAAE,EAAE,YAAY,EAChB,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE;oBACA;wBACI,EAAE,EAAE,MAAM;qBACb;oBACD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;oBAChE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;iBAC/E,IAEA,UAAU,CACE;YACjB,CAAC,CAAC,IAAI,CACA,CAAA;AAClB,CAAC,CAAA;AAED,MAAM,WAAW,GAAG,CAAC,KAAc,EAAsB,EAAE;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC/B,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACxB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,uDAAuD,KAAK,IAAI,CAAC,CAAA;QAClF,CAAC;QAED,OAAO,SAAS,CAAA;IACpB,CAAC;IAED,OAAO,UAAU,CAAA;AACrB,CAAC,CAAA;AAED,MAAM,oBAAoB,GAAG,CAAC,KAAsB,EAAW,EAAE,CAC7D,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAA;AAEvF,MAAM,YAAY,GAAG,CAAC,KAAyC,EAAW,EAAE,CACxE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAA;AAEpD,MAAM,yBAAyB,GAAG,CAC9B,OAKC,EACH,EAAE;IACA,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxC,OAAM;IACV,CAAC;IAED,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,aAAa,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;QACxF,OAAO,CAAC,IAAI,CACR,uBAAuB,OAAO,CAAC,aAAa,6CAA6C;cACvF,IAAI,OAAO,CAAC,OAAO,IAAI,CAC5B,CAAA;IACL,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;QACzD,OAAO,CAAC,IAAI,CACR,4CAA4C,OAAO,CAAC,MAAM,KAAK;cAC7D,8CAA8C,CACnD,CAAA;IACL,CAAC;AACL,CAAC,CAAA;AAED,MAAM,gBAAgB,GAAG,CAAC,QAA4B,EAAE,QAAiB,EAAE,EAAE;IACzE,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAA+B,QAAQ,CAAC;WAC5E,QAAQ,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ;QACnC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ;QACzB,CAAC,CAAC,QAAQ,CAAA;IAEd,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC7E,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QACxC,OAAM;IACV,CAAC;IAED,IACI,QAAQ;WACL,KAAK,CAAC,cAAc,CAA4B,QAAQ,CAAC;WACzD,oBAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAC/C,CAAC;QACC,OAAO,CAAC,IAAI,CACR,+GAA+G,CAClH,CAAA;IACL,CAAC;AACL,CAAC,CAAA;AAED,sBAAsB,CAAC,WAAW,GAAG,UAAU,CAAA;AAE/C,MAAM,QAAQ,GAAG,sBAA2C,CAAA;AAE5D,kBAAe,QAAQ,CAAA"}

package/cjs/component/PneFieldContext.d.ts

@@ -1,14 +1,33 @@
-export interface PneFieldContextValue {
-    controlId?: string;
+import type { AriaAttributes } from 'react';
+export interface PneFieldControlDomProps {
+    'aria-describedby'?: string;
+    'aria-disabled'?: AriaAttributes['aria-disabled'];
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
+    'aria-label'?: AriaAttributes['aria-label'];
+    'aria-labelledby'?: string;
+    'aria-required'?: AriaAttributes['aria-required'];
     disabled?: boolean;
-    error?: boolean;
-    fullWidth?: boolean;
-    helperTextId?: string;
-    labelId?: string;
-    required?: boolean;
+    id?: string;
+}
+export interface ResolvedPneFieldControlDomProps extends Omit<PneFieldControlDomProps, 'disabled' | 'id'> {
+    disabled: boolean;
+    id: string;
+}
+export interface PneFieldControlAdapter {
+    readonly controlId: string;
+    readonly disabled: boolean;
+    readonly error: boolean;
+    readonly fullWidth: boolean;
+    readonly helperTextId?: string;
+    readonly labelId?: string;
+    readonly required: boolean;
+    getControlProps: <Props extends object = PneFieldControlDomProps>(props?: Props & PneFieldControlDomProps) => Omit<Props, keyof PneFieldControlDomProps> & ResolvedPneFieldControlDomProps;
 }
 export interface PneFieldControlProps {
     ariaDescribedBy?: string;
+    ariaInvalid?: AriaAttributes['aria-invalid'];
+    ariaLabelledBy?: string;
+    ariaRequired?: AriaAttributes['aria-required'];
     disabled?: boolean;
     error?: boolean;
     fullWidth?: boolean;
@@ -19,7 +38,9 @@ export interface ResolvedPneFieldControlProps extends PneFieldControlProps {
     ariaRequired?: boolean;
     labelId?: string;
 }
-export declare const PneFieldContext: import("react").Context<PneFieldContextValue | undefined>;
-export declare const usePneFieldContext: () => PneFieldContextValue | undefined;
+export declare const PneFieldContext: import("react").Context<PneFieldControlAdapter | undefined>;
+export declare const usePneFieldControl: () => PneFieldControlAdapter | undefined;
 export declare const usePneFieldControlProps: (props?: PneFieldControlProps) => ResolvedPneFieldControlProps;
+export declare const mergeAriaIds: (...ids: Array<string | undefined>) => string | undefined;
+/** @deprecated Use `mergeAriaIds`; this alias remains for internal source compatibility. */
 export declare const mergeAriaDescribedBy: (...ids: Array<string | undefined>) => string | undefined;

package/cjs/component/PneFieldContext.js

@@ -1,31 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeAriaDescribedBy = exports.usePneFieldControlProps = exports.usePneFieldContext = exports.PneFieldContext = void 0;
+exports.mergeAriaDescribedBy = exports.mergeAriaIds = exports.usePneFieldControlProps = exports.usePneFieldControl = exports.PneFieldContext = void 0;
 const react_1 = require("react");
 exports.PneFieldContext = (0, react_1.createContext)(undefined);
-const usePneFieldContext = () => (0, react_1.useContext)(exports.PneFieldContext);
-exports.usePneFieldContext = usePneFieldContext;
+const usePneFieldControl = () => (0, react_1.useContext)(exports.PneFieldContext);
+exports.usePneFieldControl = usePneFieldControl;
 const usePneFieldControlProps = (props = {}) => {
-    const fieldContext = (0, exports.usePneFieldContext)();
+    const field = (0, exports.usePneFieldControl)();
+    const ariaInvalid = props.error === undefined
+        ? props.ariaInvalid
+        : props.error
+            ? true
+            : props.ariaInvalid ?? false;
+    const controlProps = field?.getControlProps({
+        'aria-describedby': props.ariaDescribedBy,
+        'aria-invalid': ariaInvalid,
+        'aria-labelledby': props.ariaLabelledBy,
+        'aria-required': props.ariaRequired,
+        disabled: props.disabled,
+        id: props.id,
+    });
     return {
-        ariaDescribedBy: (0, exports.mergeAriaDescribedBy)(props.ariaDescribedBy, fieldContext?.helperTextId),
-        ariaRequired: props.required !== true && fieldContext?.required
+        ariaDescribedBy: controlProps?.['aria-describedby'] ?? props.ariaDescribedBy,
+        ariaInvalid: controlProps?.['aria-invalid'] ?? ariaInvalid,
+        ariaLabelledBy: controlProps?.['aria-labelledby'] ?? props.ariaLabelledBy,
+        ariaRequired: isAriaTrue(controlProps?.['aria-required']) || isAriaTrue(props.ariaRequired)
             ? true
             : undefined,
-        disabled: props.disabled ?? fieldContext?.disabled,
-        error: props.error ?? fieldContext?.error,
-        fullWidth: props.fullWidth ?? fieldContext?.fullWidth,
-        id: props.id ?? fieldContext?.controlId,
-        labelId: fieldContext?.labelId,
+        disabled: controlProps?.disabled ?? props.disabled,
+        error: field?.error === true || props.error === true
+            ? true
+            : props.error ?? field?.error,
+        fullWidth: props.fullWidth ?? field?.fullWidth,
+        id: controlProps?.id ?? props.id,
+        labelId: field?.labelId,
         required: props.required,
     };
 };
 exports.usePneFieldControlProps = usePneFieldControlProps;
-const mergeAriaDescribedBy = (...ids) => {
+const mergeAriaIds = (...ids) => {
     const mergedIds = ids
         .flatMap(id => id?.split(/\s+/) ?? [])
         .filter((id, index, allIds) => id !== '' && allIds.indexOf(id) === index);
     return mergedIds.length > 0 ? mergedIds.join(' ') : undefined;
 };
-exports.mergeAriaDescribedBy = mergeAriaDescribedBy;
+exports.mergeAriaIds = mergeAriaIds;
+const isAriaTrue = (value) => value === true || value === 'true';
+/** @deprecated Use `mergeAriaIds`; this alias remains for internal source compatibility. */
+exports.mergeAriaDescribedBy = exports.mergeAriaIds;
 //# sourceMappingURL=PneFieldContext.js.map

package/cjs/component/PneFieldContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"PneFieldContext.js","sourceRoot":"","sources":["../../src/component/PneFieldContext.ts"],"names":[],"mappings":";;;AAAA,iCAA+C;AA0BlC,QAAA,eAAe,GAAG,IAAA,qBAAa,EAAmC,SAAS,CAAC,CAAA;AAElF,MAAM,kBAAkB,GAAG,GAAqC,EAAE,CAAC,IAAA,kBAAU,EAAC,uBAAe,CAAC,CAAA;AAAxF,QAAA,kBAAkB,sBAAsE;AAE9F,MAAM,uBAAuB,GAAG,CACnC,QAA8B,EAAE,EACJ,EAAE;IAC9B,MAAM,YAAY,GAAG,IAAA,0BAAkB,GAAE,CAAA;IAEzC,OAAO;QACH,eAAe,EAAE,IAAA,4BAAoB,EAAC,KAAK,CAAC,eAAe,EAAE,YAAY,EAAE,YAAY,CAAC;QACxF,YAAY,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,YAAY,EAAE,QAAQ;YAC3D,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,SAAS;QACf,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,YAAY,EAAE,QAAQ;QAClD,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,YAAY,EAAE,KAAK;QACzC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,YAAY,EAAE,SAAS;QACrD,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,YAAY,EAAE,SAAS;QACvC,OAAO,EAAE,YAAY,EAAE,OAAO;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;KAC3B,CAAA;AACL,CAAC,CAAA;AAjBY,QAAA,uBAAuB,2BAiBnC;AAEM,MAAM,oBAAoB,GAAG,CAChC,GAAG,GAA8B,EACf,EAAE;IACpB,MAAM,SAAS,GAAG,GAAG;SAChB,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SACrC,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,CAAA;IAE7E,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC,CAAA;AARY,QAAA,oBAAoB,wBAQhC"}
+{"version":3,"file":"PneFieldContext.js","sourceRoot":"","sources":["../../src/component/PneFieldContext.ts"],"names":[],"mappings":";;;AAAA,iCAA+C;AAoDlC,QAAA,eAAe,GAAG,IAAA,qBAAa,EAAqC,SAAS,CAAC,CAAA;AAEpF,MAAM,kBAAkB,GAAG,GAAuC,EAAE,CAAC,IAAA,kBAAU,EAAC,uBAAe,CAAC,CAAA;AAA1F,QAAA,kBAAkB,sBAAwE;AAEhG,MAAM,uBAAuB,GAAG,CACnC,QAA8B,EAAE,EACJ,EAAE;IAC9B,MAAM,KAAK,GAAG,IAAA,0BAAkB,GAAE,CAAA;IAClC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,KAAK,SAAS;QACzC,CAAC,CAAC,KAAK,CAAC,WAAW;QACnB,CAAC,CAAC,KAAK,CAAC,KAAK;YACT,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAA;IACpC,MAAM,YAAY,GAAG,KAAK,EAAE,eAAe,CAAC;QACxC,kBAAkB,EAAE,KAAK,CAAC,eAAe;QACzC,cAAc,EAAE,WAAW;QAC3B,iBAAiB,EAAE,KAAK,CAAC,cAAc;QACvC,eAAe,EAAE,KAAK,CAAC,YAAY;QACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,EAAE,EAAE,KAAK,CAAC,EAAE;KACf,CAAC,CAAA;IAEF,OAAO;QACH,eAAe,EAAE,YAAY,EAAE,CAAC,kBAAkB,CAAC,IAAI,KAAK,CAAC,eAAe;QAC5E,WAAW,EAAE,YAAY,EAAE,CAAC,cAAc,CAAC,IAAI,WAAW;QAC1D,cAAc,EAAE,YAAY,EAAE,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,cAAc;QACzE,YAAY,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC,eAAe,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC;YACvF,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,SAAS;QACf,QAAQ,EAAE,YAAY,EAAE,QAAQ,IAAI,KAAK,CAAC,QAAQ;QAClD,KAAK,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;YAChD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,EAAE,KAAK;QACjC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK,EAAE,SAAS;QAC9C,EAAE,EAAE,YAAY,EAAE,EAAE,IAAI,KAAK,CAAC,EAAE;QAChC,OAAO,EAAE,KAAK,EAAE,OAAO;QACvB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KAC3B,CAAA;AACL,CAAC,CAAA;AAlCY,QAAA,uBAAuB,2BAkCnC;AAEM,MAAM,YAAY,GAAG,CACxB,GAAG,GAA8B,EACf,EAAE;IACpB,MAAM,SAAS,GAAG,GAAG;SAChB,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SACrC,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,CAAA;IAE7E,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC,CAAA;AARY,QAAA,YAAY,gBAQxB;AAED,MAAM,UAAU,GAAG,CAAC,KAAsC,EAAW,EAAE,CACnE,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAA;AAEtC,4FAA4F;AAC/E,QAAA,oBAAoB,GAAG,oBAAY,CAAA"}