@g9tm/lynxcontrols 0.0.0-stage → 1.4.0

package/dist/fields/use-text-input.jsx

@@ -0,0 +1,237 @@
+import { G9InputType, G9TextInputDirection } from "@g9tm/lynxcontrols-foundation";
+import { KeyboardAwareTriggerContext } from "@lynx-js/lynx-ui-input";
+import { useContext, useEffect, useRef, useState } from "@lynx-js/react";
+import { startTimer } from "../base/timers.jsx";
+import { useControllableState } from "../base/use-controllable-state.jsx";
+import { g9KeyboardTargetProps } from "../host/keyboard.jsx";
+import { useG9Culture, useG9Strings } from "../provider/hooks.jsx";
+import { decimalSeparatorFor, inputTypeHasValidationRule, inputTypePrefersLeftToRight, sanitizeInputText, validateInputText } from "./input-policy.jsx";
+import { useDictation } from "./use-dictation.jsx";
+import { runTextValidator } from "./validator.jsx";
+function resolveInputTextDirection(inputTextDirection, inputType, isPassword, cultureDirection) {
+    if (inputTextDirection === G9TextInputDirection.LeftToRight) return 'ltr';
+    if (inputTextDirection === G9TextInputDirection.RightToLeft) return 'rtl';
+    if (inputTypePrefersLeftToRight(inputType) || isPassword) return 'ltr';
+    return cultureDirection;
+}
+function invokeNode(ref, method, params) {
+    const node = ref.current;
+    if (!node) return false;
+    try {
+        node.invoke({
+            method,
+            ...params ? {
+                params
+            } : {},
+            success: ()=>{},
+            fail: ()=>{}
+        }).exec();
+    } catch  {
+        return false;
+    }
+    return true;
+}
+function invokeNodeWhenReady(ref, method, params, attempts = 5) {
+    if (invokeNode(ref, method, params) || attempts <= 0) return;
+    startTimer(()=>invokeNodeWhenReady(ref, method, params, attempts - 1), 0);
+}
+function useTextInput(props, options) {
+    var _props_inputType, _props_defaultValue, _props_voiceLocale, _props_inputTextDirection;
+    const culture = useG9Culture();
+    const strings = useG9Strings();
+    const keyboardAware = useContext(KeyboardAwareTriggerContext);
+    const inputType = null != (_props_inputType = props.inputType) ? _props_inputType : G9InputType.Default;
+    const separator = decimalSeparatorFor(culture.numberingSystem);
+    const sanitize = (raw)=>sanitizeInputText(inputType, raw, props.allowedCharsPattern, separator);
+    const [text, setText] = useControllableState({
+        value: props.value,
+        defaultValue: null != (_props_defaultValue = props.defaultValue) ? _props_defaultValue : '',
+        onChange: props.onValueChange,
+        name: options.name
+    });
+    const display = sanitize(text);
+    const latestText = useRef(display);
+    latestText.current = display;
+    const elementRef = useRef(null);
+    const native = useRef('');
+    const [focused, setFocused] = useState(false);
+    const focusedRef = useRef(false);
+    const [passwordVisible, setPasswordVisible] = useState(false);
+    const [, bump] = useState(0);
+    const [validation, setValidation] = useState(null);
+    const hasValue = '' !== display;
+    const runValidation = (value)=>{
+        var _runTextValidator;
+        var _props_onValidationChange;
+        const message = null != (_runTextValidator = runTextValidator(options.validator, value)) ? _runTextValidator : validateInputText(inputType, value, props.validationPattern, props.validationErrorText, strings);
+        setValidation({
+            message,
+            hasError: props.hasError,
+            errorText: props.errorText
+        });
+        null == (_props_onValidationChange = props.onValidationChange) || _props_onValidationChange.call(props, message);
+        return null === message;
+    };
+    const hasRule = null != options.validator || inputTypeHasValidationRule(inputType, props.validationPattern);
+    const dictation = useDictation({
+        enabled: true === props.voiceEnabled,
+        locale: null != (_props_voiceLocale = props.voiceLocale) ? _props_voiceLocale : null,
+        readText: ()=>latestText.current,
+        writeText: (value)=>{
+            setText(sanitize(value), {
+                source: 'dictation'
+            });
+        },
+        ...props.onVoiceListeningStarted ? {
+            onListeningStarted: props.onVoiceListeningStarted
+        } : {},
+        ...props.onVoiceListeningEnded ? {
+            onListeningEnded: props.onVoiceListeningEnded
+        } : {},
+        ...props.onVoiceFailed ? {
+            onFailed: props.onVoiceFailed
+        } : {}
+    });
+    const refiltered = useRef(null);
+    useEffect(()=>{
+        if (display !== text && refiltered.current !== text) {
+            refiltered.current = text;
+            setText(display, {
+                source: 'programmatic'
+            });
+        }
+    });
+    const retries = useRef(0);
+    const sync = ()=>{
+        const value = latestText.current;
+        if (native.current === value) return;
+        if (invokeNode(elementRef, 'setValue', {
+            value
+        })) {
+            native.current = value;
+            retries.current = 0;
+        } else if (elementRef.current && retries.current < 5) {
+            retries.current += 1;
+            startTimer(()=>syncRef.current(), 0);
+        }
+    };
+    const syncRef = useRef(sync);
+    syncRef.current = sync;
+    const attach = useRef((node)=>{
+        elementRef.current = node;
+        if (node) syncRef.current();
+    }).current;
+    useEffect(()=>{
+        sync();
+    });
+    useEffect(()=>{
+        if (!hasValue && passwordVisible) setPasswordVisible(false);
+    }, [
+        hasValue,
+        passwordVisible
+    ]);
+    const validationCurrent = null !== validation && validation.hasError === props.hasError && validation.errorText === props.errorText;
+    const hasError = validationCurrent ? null !== validation.message : true === props.hasError;
+    const errorText = validationCurrent && null !== validation.message ? validation.message : props.errorText;
+    const onInput = (event)=>{
+        var _ref;
+        var _event_detail, _event_detail1;
+        const raw = null != (_ref = null == (_event_detail = event.detail) ? void 0 : _event_detail.value) ? _ref : '';
+        native.current = raw;
+        if (null == (_event_detail1 = event.detail) ? void 0 : _event_detail1.isComposing) return;
+        const clean = sanitize(raw);
+        latestText.current = clean;
+        setText(clean, {
+            source: 'user'
+        });
+        if (options.validateOnTextChanged) runValidation(clean);
+        bump((n)=>n + 1);
+    };
+    const onFocus = ()=>{
+        var _keyboardAware_onInputFocused, _props_onFocus;
+        focusedRef.current = true;
+        setFocused(true);
+        null == (_keyboardAware_onInputFocused = keyboardAware.onInputFocused) || _keyboardAware_onInputFocused.call(keyboardAware);
+        if (dictation.listening) dictation.stop();
+        null == (_props_onFocus = props.onFocus) || _props_onFocus.call(props);
+    };
+    const onBlur = ()=>{
+        var _keyboardAware_onInputBlurred, _props_onBlur;
+        focusedRef.current = false;
+        setFocused(false);
+        null == (_keyboardAware_onInputBlurred = keyboardAware.onInputBlurred) || _keyboardAware_onInputBlurred.call(keyboardAware);
+        if (hasRule && '' !== latestText.current) runValidation(latestText.current);
+        null == (_props_onBlur = props.onBlur) || _props_onBlur.call(props);
+    };
+    const onConfirm = ()=>{
+        var _props_onConfirm;
+        return null == (_props_onConfirm = props.onConfirm) ? void 0 : _props_onConfirm.call(props, latestText.current);
+    };
+    const focus = ()=>{
+        if (props.disabled) return;
+        invokeNode(elementRef, 'focus');
+    };
+    const blur = ()=>invokeNode(elementRef, 'blur');
+    const showMic = options.showMic({
+        available: dictation.available,
+        listening: dictation.listening,
+        hasValue
+    });
+    const pressMic = ()=>{
+        if (!dictation.listening && focusedRef.current) blur();
+        dictation.toggle();
+    };
+    const direction = resolveInputTextDirection(null != (_props_inputTextDirection = props.inputTextDirection) ? _props_inputTextDirection : G9TextInputDirection.MatchParent, inputType, true === options.isPassword, culture.direction);
+    const font = props.customFont && '' !== props.customFont.trim() ? props.customFont : 'rtl' === culture.direction ? culture.rtlFontFamily : culture.ltrFontFamily;
+    const handle = {
+        focus,
+        blur,
+        validate: ()=>runValidation(latestText.current),
+        get isListening () {
+            return dictation.listening;
+        },
+        toggleVoice: ()=>dictation.toggle(),
+        startVoice: ()=>dictation.start(),
+        stopVoice: ()=>dictation.stop(),
+        get element () {
+            return elementRef.current;
+        }
+    };
+    return {
+        text: display,
+        setText,
+        hasValue,
+        focused,
+        hasError,
+        errorText,
+        passwordVisible,
+        setPasswordVisible,
+        dictation,
+        showMic,
+        pressMic,
+        focus,
+        blur,
+        handle,
+        inputType,
+        elementProps: {
+            ...g9KeyboardTargetProps,
+            ref: attach,
+            ...props.inputId ? {
+                id: props.inputId
+            } : {},
+            'ignore-focus': true,
+            readonly: true === props.readOnly,
+            disabled: true === props.disabled,
+            maxlength: void 0 !== props.maxLength && props.maxLength > 0 ? props.maxLength : 2147483647,
+            bindinput: onInput,
+            bindfocus: onFocus,
+            bindblur: onBlur,
+            bindconfirm: onConfirm
+        },
+        textDirection: direction,
+        font
+    };
+}
+export { invokeNode, invokeNodeWhenReady, resolveInputTextDirection, useTextInput };
+
+//# sourceMappingURL=use-text-input.jsx.map

package/dist/fields/use-text-input.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields/use-text-input.jsx","sources":["../../src/fields/use-text-input.ts"],"sourcesContent":["import { G9InputType, type G9KeyboardType, G9TextInputDirection } from '@g9tm/lynxcontrols-foundation';\nimport { KeyboardAwareTriggerContext } from '@lynx-js/lynx-ui-input';\nimport { useContext, useEffect, useRef, useState } from '@lynx-js/react';\nimport type { NodesRef } from '@lynx-js/types';\nimport { startTimer } from '../base/timers';\nimport { useControllableState } from '../base/use-controllable-state';\nimport { g9KeyboardTargetProps } from '../host/keyboard';\nimport { useG9Culture, useG9Strings } from '../provider/hooks';\nimport {\n  decimalSeparatorFor,\n  inputTypeHasValidationRule,\n  inputTypePrefersLeftToRight,\n  sanitizeInputText,\n  validateInputText,\n} from './input-policy';\nimport type { G9OutlinedFieldProps } from './outlined-field';\nimport { useDictation } from './use-dictation';\nimport { type G9TextValidator, runTextValidator } from './validator';\n\n/** Where a value change came from (plan/specs/03 §3). */\nexport type G9ValueChangeSource = 'user' | 'dictation' | 'clear' | 'programmatic';\n\n/** Payload of `onValueChange`. */\nexport interface G9ValueChangeDetails {\n  readonly source: G9ValueChangeSource;\n}\n\n/** Props the text inputs (`G9TextEntry`, `G9Editor`, `G9SearchEntry`) share on top of the outlined-field props. */\nexport interface G9TextInputProps extends G9OutlinedFieldProps {\n  /** The text (controlled; MAUI `Text`). Present, the caller owns it and must apply `onValueChange`. */\n  readonly value?: string;\n  /** Initial text while uncontrolled. Default `''`. */\n  readonly defaultValue?: string;\n  /**\n   * Once per change of the field's value, with where it came from: `'user'` (typing, paste), `'dictation'`,\n   * `'clear'` (the clear button) or `'programmatic'` (the field re-filtered a value it was given, e.g. after an\n   * `inputType` change). Never for a value the parent pushed in that needed no filtering.\n   */\n  readonly onValueChange?: (value: string, details: G9ValueChangeDetails) => void;\n  /** On-screen keyboard; used when `inputType` is `'default'` (any other type picks its own). Default `'default'`. */\n  readonly keyboardType?: G9KeyboardType;\n  /** Semantic input type: keyboard, live filter and blur validation. Default `'default'`. */\n  readonly inputType?: G9InputType;\n  /** Per-character filter regex (a single character class) for `inputType: 'custom'`. */\n  readonly allowedCharsPattern?: string | null;\n  /** Blur validation regex for `inputType: 'custom'`. An invalid pattern fails closed. */\n  readonly validationPattern?: string | null;\n  /** Message for a failed type validation; default the culture's `invalidEmail` / `invalidUrl` / `invalidValue`. */\n  readonly validationErrorText?: string | null;\n  /** Direction of the entered text; `'matchParent'` (default) pins numbers, phone, email, URL and passwords LTR. */\n  readonly inputTextDirection?: G9TextInputDirection;\n  /** Font family of the entered text; default the culture's font. */\n  readonly customFont?: string | null;\n  /** Offer dictation through `services.speech` (hidden without the service or recogniser). Default false. */\n  readonly voiceEnabled?: boolean;\n  /** Locale to recognise (MAUI `VoiceCulture`); default the active culture. */\n  readonly voiceLocale?: string | null;\n  readonly onVoiceListeningStarted?: () => void;\n  readonly onVoiceListeningEnded?: () => void;\n  /** Dictation could not run or finish; a localized message for a toast. */\n  readonly onVoiceFailed?: (message: string) => void;\n  /** Validation ran (blur, `validateOnTextChanged` or `validate()`): the message, or `null` when valid. */\n  readonly onValidationChange?: (message: string | null) => void;\n  readonly onFocus?: () => void;\n  readonly onBlur?: () => void;\n  /** The keyboard's confirm key was pressed. */\n  readonly onConfirm?: (value: string) => void;\n  /** Element id of the inner `<input>`/`<textarea>`. */\n  readonly inputId?: string;\n}\n\n/** Imperative handle of the text inputs (MAUI public methods). */\nexport interface G9TextInputHandle {\n  /** Focuses the inner element (raises the keyboard). */\n  focus(): void;\n  /** Removes focus (hides the keyboard). */\n  blur(): void;\n  /** Runs the validator and the type rule now; sets or clears the error; `true` when valid (MAUI `Validate`). */\n  validate(): boolean;\n  /** `true` while dictating (MAUI `IsListening`). */\n  readonly isListening: boolean;\n  /** MAUI `ToggleVoiceAsync`. */\n  toggleVoice(): Promise<void>;\n  /** MAUI `StartVoiceAsync`. */\n  startVoice(): Promise<void>;\n  /** MAUI `StopVoiceAsync`; safe when nothing runs. */\n  stopVoice(): Promise<void>;\n  /** The inner element's node ref (MAUI `InnerEntry` / `InnerEditor`), for `invoke` calls G9 does not wrap. */\n  readonly element: G9NodeRef | null;\n}\n\n/** The Lynx node ref of a field's inner element. */\nexport type G9NodeRef = NodesRef;\n\n/** Lynx input event detail. */\ninterface InputDetail {\n  readonly value?: string;\n  readonly isComposing?: boolean;\n}\n\n/** Resolves the entered text's direction (MAUI `ResolveInputFlowDirection`). */\nexport function resolveInputTextDirection(\n  inputTextDirection: G9TextInputDirection,\n  inputType: G9InputType,\n  isPassword: boolean,\n  cultureDirection: 'ltr' | 'rtl',\n): 'ltr' | 'rtl' {\n  if (inputTextDirection === G9TextInputDirection.LeftToRight) return 'ltr';\n  if (inputTextDirection === G9TextInputDirection.RightToLeft) return 'rtl';\n  if (inputTypePrefersLeftToRight(inputType) || isPassword) return 'ltr';\n  return cultureDirection;\n}\n\n/** Calls a UI method on a node; a missing node or a failing call is ignored (the element is gone). */\nexport function invokeNode(\n  ref: { current: G9NodeRef | null },\n  method: string,\n  params?: Record<string, unknown>,\n): boolean {\n  const node = ref.current;\n  if (!node) return false;\n  try {\n    node\n      .invoke({\n        method,\n        ...(params ? { params } : {}),\n        success: () => {},\n        fail: () => {},\n      })\n      .exec();\n  } catch {\n    // The element was unmounted between the call and its execution.\n    return false;\n  }\n  return true;\n}\n\n/**\n * {@link invokeNode}, retried on the next ticks (up to `attempts` times) while the element is not created natively\n * yet, e.g. a focus requested during the first commit.\n */\nexport function invokeNodeWhenReady(\n  ref: { current: G9NodeRef | null },\n  method: string,\n  params?: Record<string, unknown>,\n  attempts = 5,\n): void {\n  if (invokeNode(ref, method, params) || attempts <= 0) return;\n  startTimer(() => invokeNodeWhenReady(ref, method, params, attempts - 1), 0);\n}\n\ninterface ValidationResult {\n  readonly message: string | null;\n  // The external error props this result overrides; new props from the parent win again.\n  readonly hasError: boolean | undefined;\n  readonly errorText: string | null | undefined;\n}\n\n/** Options of {@link useTextInput}. */\nexport interface G9TextInputCoreOptions {\n  /** Name for the controlled/uncontrolled diagnostic, e.g. `'G9TextEntry.value'`. */\n  readonly name: string;\n  /** Whether the microphone is shown, given the dictation and value state. */\n  readonly showMic: (state: { available: boolean; listening: boolean; hasValue: boolean }) => boolean;\n  /** Extra validator (`G9TextEntry.validator`; the editor has none). */\n  readonly validator?: G9TextValidator | null;\n  /** Validate on every change (`G9TextEntry.validateOnTextChanged`). */\n  readonly validateOnTextChanged?: boolean;\n  /** A password field (its text is pinned LTR). */\n  readonly isPassword?: boolean;\n}\n\n/**\n * The state machine behind the text inputs: value ownership, the live filter, the native element sync, focus,\n * validation and dictation. Returns what the input element and the outlined frame need.\n */\nexport function useTextInput(props: G9TextInputProps, options: G9TextInputCoreOptions) {\n  const culture = useG9Culture();\n  const strings = useG9Strings();\n  const keyboardAware = useContext(KeyboardAwareTriggerContext);\n  const inputType = props.inputType ?? G9InputType.Default;\n  const separator = decimalSeparatorFor(culture.numberingSystem);\n  const sanitize = (raw: string) => sanitizeInputText(inputType, raw, props.allowedCharsPattern, separator);\n\n  const [text, setText] = useControllableState<string, [G9ValueChangeDetails]>({\n    value: props.value,\n    defaultValue: props.defaultValue ?? '',\n    onChange: props.onValueChange,\n    name: options.name,\n  });\n  const display = sanitize(text);\n  const latestText = useRef(display);\n  latestText.current = display;\n\n  const elementRef = useRef<NodesRef | null>(null);\n  const native = useRef('');\n  const [focused, setFocused] = useState(false);\n  const focusedRef = useRef(false);\n  const [passwordVisible, setPasswordVisible] = useState(false);\n  const [, bump] = useState(0);\n  const [validation, setValidation] = useState<ValidationResult | null>(null);\n  const hasValue = display !== '';\n\n  const runValidation = (value: string): boolean => {\n    const message =\n      runTextValidator(options.validator, value) ??\n      validateInputText(inputType, value, props.validationPattern, props.validationErrorText, strings);\n    setValidation({ message, hasError: props.hasError, errorText: props.errorText });\n    props.onValidationChange?.(message);\n    return message === null;\n  };\n  const hasRule = options.validator != null || inputTypeHasValidationRule(inputType, props.validationPattern);\n\n  const dictation = useDictation({\n    enabled: props.voiceEnabled === true,\n    locale: props.voiceLocale ?? null,\n    readText: () => latestText.current,\n    writeText: (value) => {\n      setText(sanitize(value), { source: 'dictation' });\n    },\n    ...(props.onVoiceListeningStarted ? { onListeningStarted: props.onVoiceListeningStarted } : {}),\n    ...(props.onVoiceListeningEnded ? { onListeningEnded: props.onVoiceListeningEnded } : {}),\n    ...(props.onVoiceFailed ? { onFailed: props.onVoiceFailed } : {}),\n  });\n\n  // A value the field was given that its filter rejects is replaced once (MAUI OnTextChanged writes it back).\n  const refiltered = useRef<string | null>(null);\n  useEffect(() => {\n    if (display !== text && refiltered.current !== text) {\n      refiltered.current = text;\n      setText(display, { source: 'programmatic' });\n    }\n  });\n\n  // Keep the native element showing the field's value (lynx-ui pattern: `invoke('setValue')`). The node ref can\n  // attach after the first effect, so attaching syncs too.\n  const retries = useRef(0);\n  const sync = () => {\n    const value = latestText.current;\n    if (native.current === value) return;\n    if (invokeNode(elementRef, 'setValue', { value })) {\n      native.current = value;\n      retries.current = 0;\n    } else if (elementRef.current && retries.current < 5) {\n      // The element is not created natively yet (first commit): try again on the next tick.\n      retries.current += 1;\n      startTimer(() => syncRef.current(), 0);\n    }\n  };\n  const syncRef = useRef(sync);\n  syncRef.current = sync;\n  const attach = useRef((node: NodesRef | null) => {\n    elementRef.current = node;\n    if (node) syncRef.current();\n  }).current;\n  useEffect(() => {\n    sync();\n  });\n\n  // Clearing the value re-masks a revealed password (MAUI OnTextChanged).\n  useEffect(() => {\n    if (!hasValue && passwordVisible) setPasswordVisible(false);\n  }, [hasValue, passwordVisible]);\n\n  // New external error props win over an earlier validation result.\n  const validationCurrent =\n    validation !== null && validation.hasError === props.hasError && validation.errorText === props.errorText;\n  const hasError = validationCurrent ? validation.message !== null : props.hasError === true;\n  const errorText = validationCurrent && validation.message !== null ? validation.message : props.errorText;\n\n  const onInput = (event: { detail?: InputDetail }) => {\n    const raw = event.detail?.value ?? '';\n    native.current = raw;\n    // IME composition is never interrupted: the composed text is filtered when it is committed.\n    if (event.detail?.isComposing) return;\n    const clean = sanitize(raw);\n    latestText.current = clean;\n    setText(clean, { source: 'user' });\n    if (options.validateOnTextChanged) runValidation(clean);\n    bump((n) => n + 1);\n  };\n  const onFocus = () => {\n    focusedRef.current = true;\n    setFocused(true);\n    keyboardAware.onInputFocused?.();\n    // Tapping the field while dictating means typing: end the session (ADR-0024).\n    if (dictation.listening) void dictation.stop();\n    props.onFocus?.();\n  };\n  const onBlur = () => {\n    focusedRef.current = false;\n    setFocused(false);\n    keyboardAware.onInputBlurred?.();\n    // Only fields with a rule validate on blur, so an externally set error survives.\n    if (hasRule && latestText.current !== '') runValidation(latestText.current);\n    props.onBlur?.();\n  };\n  const onConfirm = () => props.onConfirm?.(latestText.current);\n\n  const focus = () => {\n    if (props.disabled) return;\n    invokeNode(elementRef, 'focus');\n  };\n  const blur = () => invokeNode(elementRef, 'blur');\n\n  const showMic = options.showMic({ available: dictation.available, listening: dictation.listening, hasValue });\n  const pressMic = () => {\n    // The microphone never focuses the field, and starting takes the keyboard down (ADR-0024).\n    if (!dictation.listening && focusedRef.current) blur();\n    void dictation.toggle();\n  };\n\n  const direction = resolveInputTextDirection(\n    props.inputTextDirection ?? G9TextInputDirection.MatchParent,\n    inputType,\n    options.isPassword === true,\n    culture.direction,\n  );\n  const font =\n    props.customFont && props.customFont.trim() !== ''\n      ? props.customFont\n      : culture.direction === 'rtl'\n        ? culture.rtlFontFamily\n        : culture.ltrFontFamily;\n\n  const handle: G9TextInputHandle = {\n    focus,\n    blur,\n    validate: () => runValidation(latestText.current),\n    get isListening() {\n      return dictation.listening;\n    },\n    toggleVoice: () => dictation.toggle(),\n    startVoice: () => dictation.start(),\n    stopVoice: () => dictation.stop(),\n    get element() {\n      return elementRef.current;\n    },\n  };\n\n  return {\n    text: display,\n    setText,\n    hasValue,\n    focused,\n    hasError,\n    errorText,\n    passwordVisible,\n    setPasswordVisible,\n    dictation,\n    showMic,\n    pressMic,\n    focus,\n    blur,\n    handle,\n    inputType,\n    /** Element attributes and handlers shared by `<input>` and `<textarea>`. */\n    elementProps: {\n      ...g9KeyboardTargetProps,\n      ref: attach,\n      ...(props.inputId ? { id: props.inputId } : {}),\n      'ignore-focus': true,\n      readonly: props.readOnly === true,\n      disabled: props.disabled === true,\n      maxlength: props.maxLength !== undefined && props.maxLength > 0 ? props.maxLength : 2147483647,\n      bindinput: onInput,\n      bindfocus: onFocus,\n      bindblur: onBlur,\n      bindconfirm: onConfirm,\n    },\n    textDirection: direction,\n    font,\n  };\n}\n"],"names":["resolveInputTextDirection","inputTextDirection","inputType","isPassword","cultureDirection","G9TextInputDirection","inputTypePrefersLeftToRight","invokeNode","ref","method","params","node","invokeNodeWhenReady","attempts","startTimer","useTextInput","props","options","_props_inputType","_props_defaultValue","_props_voiceLocale","_props_inputTextDirection","culture","useG9Culture","strings","useG9Strings","keyboardAware","useContext","KeyboardAwareTriggerContext","G9InputType","separator","decimalSeparatorFor","sanitize","raw","sanitizeInputText","text","setText","useControllableState","display","latestText","useRef","elementRef","native","focused","setFocused","useState","focusedRef","passwordVisible","setPasswordVisible","bump","validation","setValidation","hasValue","runValidation","value","_runTextValidator","message","validateInputText","hasRule","inputTypeHasValidationRule","dictation","useDictation","refiltered","useEffect","retries","sync","syncRef","attach","validationCurrent","hasError","errorText","onInput","event","_event_detail","_event_detail1","clean","n","onFocus","onBlur","onConfirm","focus","blur","showMic","pressMic","direction","font","handle","g9KeyboardTargetProps","undefined"],"mappings":"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"}

package/dist/fields/validator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A field validator (MAUI `IG9TextValidator`): returns the error message for a value, or `null`/`undefined` when it
+ * is valid. Either an object with `validate` (MAUI shape) or a plain function.
+ */
+export type G9TextValidator = {
+    validate(text: string | null): string | null | undefined;
+} | ((text: string | null) => string | null | undefined);
+/** Runs a {@link G9TextValidator}; a blank message counts as valid (MAUI `string.IsNullOrWhiteSpace`). */
+export declare function runTextValidator(validator: G9TextValidator | null | undefined, text: string | null): string | null;
+/** Validators for common rules, composable with {@link combineValidators}. */
+export declare function requiredValidator(message: string): G9TextValidator;
+/** The first message any validator returns, in order. */
+export declare function combineValidators(...validators: ReadonlyArray<G9TextValidator>): G9TextValidator;
+//# sourceMappingURL=validator.d.ts.map

package/dist/fields/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/fields/validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GAC5D,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEzD,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAIlH;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAElE;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,GAAG,UAAU,EAAE,aAAa,CAAC,eAAe,CAAC,GAAG,eAAe,CAQhG"}

package/dist/fields/validator.jsx

@@ -0,0 +1,20 @@
+function runTextValidator(validator, text) {
+    if (!validator) return null;
+    const message = 'function' == typeof validator ? validator(text) : validator.validate(text);
+    return null == message || '' === message.trim() ? null : message;
+}
+function requiredValidator(message) {
+    return (text)=>null == text || '' === text.trim() ? message : null;
+}
+function combineValidators(...validators) {
+    return (text)=>{
+        for (const validator of validators){
+            const message = runTextValidator(validator, text);
+            if (message) return message;
+        }
+        return null;
+    };
+}
+export { combineValidators, requiredValidator, runTextValidator };
+
+//# sourceMappingURL=validator.jsx.map

package/dist/fields/validator.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields/validator.jsx","sources":["../../src/fields/validator.ts"],"sourcesContent":["/**\n * A field validator (MAUI `IG9TextValidator`): returns the error message for a value, or `null`/`undefined` when it\n * is valid. Either an object with `validate` (MAUI shape) or a plain function.\n */\nexport type G9TextValidator =\n  | { validate(text: string | null): string | null | undefined }\n  | ((text: string | null) => string | null | undefined);\n\n/** Runs a {@link G9TextValidator}; a blank message counts as valid (MAUI `string.IsNullOrWhiteSpace`). */\nexport function runTextValidator(validator: G9TextValidator | null | undefined, text: string | null): string | null {\n  if (!validator) return null;\n  const message = typeof validator === 'function' ? validator(text) : validator.validate(text);\n  return message == null || message.trim() === '' ? null : message;\n}\n\n/** Validators for common rules, composable with {@link combineValidators}. */\nexport function requiredValidator(message: string): G9TextValidator {\n  return (text) => (text == null || text.trim() === '' ? message : null);\n}\n\n/** The first message any validator returns, in order. */\nexport function combineValidators(...validators: ReadonlyArray<G9TextValidator>): G9TextValidator {\n  return (text) => {\n    for (const validator of validators) {\n      const message = runTextValidator(validator, text);\n      if (message) return message;\n    }\n    return null;\n  };\n}\n"],"names":["runTextValidator","validator","text","message","requiredValidator","combineValidators","validators"],"mappings":"AASO,SAASA,iBAAiBC,SAA6C,EAAEC,IAAmB;IACjG,IAAI,CAACD,WAAW,OAAO;IACvB,MAAME,UAAU,AAAqB,cAArB,OAAOF,YAA2BA,UAAUC,QAAQD,UAAU,QAAQ,CAACC;IACvF,OAAOC,AAAW,QAAXA,WAAmBA,AAAmB,OAAnBA,QAAQ,IAAI,KAAY,OAAOA;AAC3D;AAGO,SAASC,kBAAkBD,OAAe;IAC/C,OAAO,CAACD,OAAUA,AAAQ,QAARA,QAAgBA,AAAgB,OAAhBA,KAAK,IAAI,KAAYC,UAAU;AACnE;AAGO,SAASE,kBAAkB,GAAGC,UAA0C;IAC7E,OAAO,CAACJ;QACN,KAAK,MAAMD,aAAaK,WAAY;YAClC,MAAMH,UAAUH,iBAAiBC,WAAWC;YAC5C,IAAIC,SAAS,OAAOA;QACtB;QACA,OAAO;IACT;AACF"}

package/dist/host/back.d.ts

@@ -0,0 +1,42 @@
+import { type G9Layer } from './layers.js';
+/** What a back handler did: consumed the press, or let the next handler (and finally the app exit) have it. */
+export type G9BackResult = 'handled' | 'pass';
+/**
+ * A back handler. `'handled'` (or `true`, MAUI `OnHardwareBackPressed` / `TryHandleInAppBack` returned `bool`)
+ * consumes the press; `'pass'` (or `false`) lets it continue.
+ */
+export type G9BackHandler = () => G9BackResult | boolean;
+/** Where a handler sits in the back order. */
+export interface G9BackOptions {
+    /**
+     * The layer the handler belongs to. Handlers of a higher layer run first (popups before sheets before the page,
+     * MAUI's order), then newest first within a layer. Default `'content'` (the page's in-app back).
+     */
+    readonly layer?: G9Layer;
+}
+/** The back handlers of one host (plan/specs/01 §5): a LIFO per layer, top layer first. */
+export interface G9BackStack {
+    /** Number of registered handlers. */
+    readonly size: number;
+    /** Registers `handler`; returns its unregister function (idempotent). */
+    push(handler: G9BackHandler, options?: G9BackOptions): () => void;
+    /**
+     * Offers one back press to the handlers in order until one handles it. While the host suppresses back (MAUI
+     * `IsHardwareBackSuppressed`) the press is swallowed before any handler runs and reported `'handled'`.
+     * A handler that throws is reported to `onHandlerError` and counts as `'handled'`: a broken handler must never turn
+     * a back press into leaving the app.
+     */
+    dispatch(): G9BackResult;
+    /** Drops every handler (host unmount). */
+    clear(): void;
+}
+/** Options of {@link createBackStack}. */
+export interface G9BackStackOptions {
+    /** Read on every dispatch; `true` swallows the press. */
+    readonly isSuppressed?: () => boolean;
+    /** Receives an error thrown by a handler. */
+    readonly onHandlerError?: (error: unknown) => void;
+}
+/** Creates an empty {@link G9BackStack}. */
+export declare function createBackStack(options?: G9BackStackOptions): G9BackStack;
+//# sourceMappingURL=back.d.ts.map

package/dist/host/back.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"back.d.ts","sourceRoot":"","sources":["../../src/host/back.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,UAAU,CAAC;AAEnD,+GAA+G;AAC/G,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,YAAY,GAAG,OAAO,CAAC;AAEzD,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAClE;;;;;OAKG;IACH,QAAQ,IAAI,YAAY,CAAC;IACzB,0CAA0C;IAC1C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAQD,4CAA4C;AAC5C,wBAAgB,eAAe,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAmC7E"}

package/dist/host/back.jsx

@@ -0,0 +1,47 @@
+import { layerRank } from "./layers.jsx";
+function createBackStack(options = {}) {
+    const entries = new Set();
+    let sequence = 0;
+    return {
+        get size () {
+            return entries.size;
+        },
+        push (handler, pushOptions) {
+            var _ref;
+            sequence += 1;
+            const entry = {
+                handler,
+                rank: layerRank(null != (_ref = null == pushOptions ? void 0 : pushOptions.layer) ? _ref : 'content'),
+                sequence
+            };
+            entries.add(entry);
+            return ()=>{
+                entries.delete(entry);
+            };
+        },
+        dispatch () {
+            var _options_isSuppressed;
+            if (null == (_options_isSuppressed = options.isSuppressed) ? void 0 : _options_isSuppressed.call(options)) return 'handled';
+            const ordered = Array.from(entries).sort((a, b)=>b.rank - a.rank || b.sequence - a.sequence);
+            for (const entry of ordered){
+                if (!entries.has(entry)) continue;
+                let result;
+                try {
+                    result = entry.handler();
+                } catch (error) {
+                    var _options_onHandlerError;
+                    null == (_options_onHandlerError = options.onHandlerError) || _options_onHandlerError.call(options, error);
+                    return 'handled';
+                }
+                if ('handled' === result || true === result) return 'handled';
+            }
+            return 'pass';
+        },
+        clear () {
+            entries.clear();
+        }
+    };
+}
+export { createBackStack };
+
+//# sourceMappingURL=back.jsx.map

package/dist/host/back.jsx.map

@@ -0,0 +1 @@
+{"version":3,"file":"host/back.jsx","sources":["../../src/host/back.ts"],"sourcesContent":["import { type G9Layer, layerRank } from './layers';\n\n/** What a back handler did: consumed the press, or let the next handler (and finally the app exit) have it. */\nexport type G9BackResult = 'handled' | 'pass';\n\n/**\n * A back handler. `'handled'` (or `true`, MAUI `OnHardwareBackPressed` / `TryHandleInAppBack` returned `bool`)\n * consumes the press; `'pass'` (or `false`) lets it continue.\n */\nexport type G9BackHandler = () => G9BackResult | boolean;\n\n/** Where a handler sits in the back order. */\nexport interface G9BackOptions {\n  /**\n   * The layer the handler belongs to. Handlers of a higher layer run first (popups before sheets before the page,\n   * MAUI's order), then newest first within a layer. Default `'content'` (the page's in-app back).\n   */\n  readonly layer?: G9Layer;\n}\n\n/** The back handlers of one host (plan/specs/01 §5): a LIFO per layer, top layer first. */\nexport interface G9BackStack {\n  /** Number of registered handlers. */\n  readonly size: number;\n  /** Registers `handler`; returns its unregister function (idempotent). */\n  push(handler: G9BackHandler, options?: G9BackOptions): () => void;\n  /**\n   * Offers one back press to the handlers in order until one handles it. While the host suppresses back (MAUI\n   * `IsHardwareBackSuppressed`) the press is swallowed before any handler runs and reported `'handled'`.\n   * A handler that throws is reported to `onHandlerError` and counts as `'handled'`: a broken handler must never turn\n   * a back press into leaving the app.\n   */\n  dispatch(): G9BackResult;\n  /** Drops every handler (host unmount). */\n  clear(): void;\n}\n\n/** Options of {@link createBackStack}. */\nexport interface G9BackStackOptions {\n  /** Read on every dispatch; `true` swallows the press. */\n  readonly isSuppressed?: () => boolean;\n  /** Receives an error thrown by a handler. */\n  readonly onHandlerError?: (error: unknown) => void;\n}\n\ninterface Entry {\n  readonly handler: G9BackHandler;\n  readonly rank: number;\n  readonly sequence: number;\n}\n\n/** Creates an empty {@link G9BackStack}. */\nexport function createBackStack(options: G9BackStackOptions = {}): G9BackStack {\n  const entries = new Set<Entry>();\n  let sequence = 0;\n  return {\n    get size() {\n      return entries.size;\n    },\n    push(handler, pushOptions) {\n      sequence += 1;\n      const entry: Entry = { handler, rank: layerRank(pushOptions?.layer ?? 'content'), sequence };\n      entries.add(entry);\n      return () => {\n        entries.delete(entry);\n      };\n    },\n    dispatch() {\n      if (options.isSuppressed?.()) return 'handled';\n      const ordered = Array.from(entries).sort((a, b) => b.rank - a.rank || b.sequence - a.sequence);\n      for (const entry of ordered) {\n        if (!entries.has(entry)) continue;\n        let result: G9BackResult | boolean;\n        try {\n          result = entry.handler();\n        } catch (error) {\n          options.onHandlerError?.(error);\n          return 'handled';\n        }\n        if (result === 'handled' || result === true) return 'handled';\n      }\n      return 'pass';\n    },\n    clear() {\n      entries.clear();\n    },\n  };\n}\n"],"names":["createBackStack","options","entries","Set","sequence","handler","pushOptions","entry","layerRank","ordered","Array","a","b","result","error"],"mappings":";AAoDO,SAASA,gBAAgBC,UAA8B,CAAC,CAAC;IAC9D,MAAMC,UAAU,IAAIC;IACpB,IAAIC,WAAW;IACf,OAAO;QACL,IAAI;YACF,OAAOF,QAAQ,IAAI;QACrB;QACA,MAAKG,OAAO,EAAEC,WAAW;;YACvBF,YAAY;YACZ,MAAMG,QAAe;gBAAEF;gBAAS,MAAMG,UAAU,QAADA,CAAAA,OAACF,QAAAA,cAAAA,KAAAA,IAAAA,YAAa,KAAK,AAAD,IAAC,OAAI;gBAAYF;YAAS;YAC3FF,QAAQ,GAAG,CAACK;YACZ,OAAO;gBACLL,QAAQ,MAAM,CAACK;YACjB;QACF;QACA;gBACMN;YAAJ,IAAI,QAAAA,CAAAA,wBAAAA,QAAQ,YAAY,AAAD,IAAnBA,KAAAA,IAAAA,sBAAAA,IAAAA,CAAAA,UAA0B,OAAO;YACrC,MAAMQ,UAAUC,MAAM,IAAI,CAACR,SAAS,IAAI,CAAC,CAACS,GAAGC,IAAMA,EAAE,IAAI,GAAGD,EAAE,IAAI,IAAIC,EAAE,QAAQ,GAAGD,EAAE,QAAQ;YAC7F,KAAK,MAAMJ,SAASE,QAAS;gBAC3B,IAAI,CAACP,QAAQ,GAAG,CAACK,QAAQ;gBACzB,IAAIM;gBACJ,IAAI;oBACFA,SAASN,MAAM,OAAO;gBACxB,EAAE,OAAOO,OAAO;wBACdb;4BAAAA,CAAAA,0BAAAA,QAAQ,cAAc,AAAD,KAArBA,wBAAAA,IAAAA,CAAAA,SAAyBa;oBACzB,OAAO;gBACT;gBACA,IAAID,AAAW,cAAXA,UAAwBA,AAAW,SAAXA,QAAiB,OAAO;YACtD;YACA,OAAO;QACT;QACA;YACEX,QAAQ,KAAK;QACf;IACF;AACF"}

package/dist/host/hooks.d.ts

@@ -0,0 +1,85 @@
+import { type G9AbortSignal } from '@g9tm/lynxcontrols-foundation';
+import { type ReactNode } from '@lynx-js/react';
+import type { G9BackHandler } from './back.js';
+import type { G9Layer, G9OverlayLayer } from './layers.js';
+import type { G9HostReadinessSnapshot } from './readiness.js';
+import type { G9HostHandle, G9HostInsets } from './registry.js';
+/** The nearest `G9Host`. Throws `host-missing` outside one. */
+export declare function useG9Host(): G9HostHandle;
+/** Insets of the nearest host (MAUI `TopSafeAreaInset` … `BottomSafeAreaWithTabBar`). Re-renders when they change. */
+export declare function useG9HostInsets(): G9HostInsets;
+/** Readiness of the nearest host, plus `release` (MAUI `ReleasePageLoadingOverlay`) and `whenDismissed`. */
+export interface G9HostReadyState extends G9HostReadinessSnapshot {
+    release(): void;
+    whenDismissed(): Promise<void>;
+}
+/**
+ * The nearest host's ready state and loading cover (MAUI `ReleasePageLoadingOverlay`, `PageLoadingOverlayDismissed`,
+ * `G9ContentViewBase.ReleaseHostPageLoadingOverlay`). A page with `manualRelease` calls `release()` when its first
+ * meaningful frame is ready.
+ */
+export declare function useG9HostReady(): G9HostReadyState;
+/** Options of {@link useG9Back}. */
+export interface G9UseBackOptions {
+    /** The layer the handler belongs to (overlays pass theirs so they are asked first). Default `'content'`. */
+    readonly layer?: G9Layer;
+    /** Register only while `true`. Default `true`. */
+    readonly enabled?: boolean;
+}
+/**
+ * Registers a back handler on the nearest host while mounted (and enabled). Handlers of higher layers run first, then
+ * newest first; returning `'handled'` (or `true`) consumes the press, `'pass'` lets it continue. When nothing handles
+ * it, the provider calls `services.host.exit()`. The latest `handler` is always called.
+ */
+export declare function useG9Back(handler: G9BackHandler, options?: G9UseBackOptions): void;
+/** Options of {@link useG9LayerItem}. */
+export interface G9UseLayerItemOptions {
+    /** Ordering inside the layer (lower paints below). Default 0. */
+    readonly order?: number;
+    /** Mount only while `true`. Default `true`. */
+    readonly enabled?: boolean;
+}
+/**
+ * Mounts `element` into an overlay layer of the nearest host while the calling component is mounted (and enabled),
+ * keeping it in step with `element`. The key must be unique within the layer.
+ */
+export declare function useG9LayerItem(layer: G9OverlayLayer, key: string, element: ReactNode, options?: G9UseLayerItemOptions): void;
+/** Inputs of {@link useG9Activation} (MAUI `G9ContentViewBase`). */
+export interface G9ActivationOptions {
+    /** Whether this view is the active one (MAUI `Activate` / `Deactivate`, driven by the hosting page). */
+    readonly active: boolean;
+    /** First activation only (MAUI `OnFirstActivatedAsync`): heavy one-shot setup. */
+    readonly onFirstActivated?: (context: {
+        readonly signal: G9AbortSignal;
+    }) => void | Promise<void>;
+    /** Every activation, after the first-activation work (MAUI `OnActivatedAsync`). */
+    readonly onActivated?: (context: {
+        readonly signal: G9AbortSignal;
+    }) => void | Promise<void>;
+    /** Every deactivation, after the activation signal was aborted (MAUI `OnDeactivated`). */
+    readonly onDeactivated?: () => void;
+    /** Ask the app to pause background work while active (MAUI `SuppressesBackgroundWork`). Default `false`. */
+    readonly suppressesBackgroundWork?: boolean;
+    /** Back handling while active (MAUI `OnHardwareBackPressed`); asked after overlays. */
+    readonly onBack?: G9BackHandler;
+    /** Names the view in diagnostics. Default `'G9ActivatedView'`. */
+    readonly name?: string;
+}
+/**
+ * Activation lifecycle of a view kept alive across tab switches (MAUI `G9ContentViewBase`): a fresh abort signal per
+ * activation (aborted on deactivation and unmount), first-activation and every-activation work run through the
+ * provider's safe executor, the app's background-work pause held while active
+ * (`settings.backgroundWorkSuppression`), and back handling while active. Unmounting while active deactivates too
+ * (MAUI handler teardown: signal aborted, pause released, `onDeactivated` called). Returns whether the view is active.
+ */
+export declare function useG9Activation(options: G9ActivationOptions): {
+    readonly active: boolean;
+};
+/**
+ * Holds Android's pan soft-input mode while `enabled` (MAUI `G9KeyboardHelper.UseAndroidPanSoftInputMode` scoped to
+ * a sheet or page); restores on disable and unmount.
+ */
+export declare function useG9PanSoftInputMode(enabled?: boolean): void;
+/** The keyboard dismiss path (MAUI `G9KeyboardHelper.HideKeyboardAndClearFocus`): `services.host.hideKeyboard`. */
+export declare function useG9HideKeyboard(): () => void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/host/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/host/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,SAAS,EAAiE,MAAM,gBAAgB,CAAC;AAG/G,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,QAAQ,CAAC;AAG1D,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM7D,+DAA+D;AAC/D,wBAAgB,SAAS,IAAI,YAAY,CAIxC;AAED,sHAAsH;AACtH,wBAAgB,eAAe,IAAI,YAAY,CAI9C;AAED,4GAA4G;AAC5G,MAAM,WAAW,gBAAiB,SAAQ,uBAAuB;IAC/D,OAAO,IAAI,IAAI,CAAC;IAChB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CAKjD;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAStF;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,EAClB,OAAO,GAAE,qBAA0B,GAClC,IAAI,CAQN;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,wGAAwG;IACxG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClG,mFAAmF;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IACpC,4GAA4G;IAC5G,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAiE1F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,UAAO,GAAG,IAAI,CAG1D;AAED,mHAAmH;AACnH,wBAAgB,iBAAiB,IAAI,MAAM,IAAI,CAG9C"}