@net-advantage/jo-ui-input

Publishable input primitives package.

The input follows a strict MVVM split. The model owns kind behavior, parsing, and formatting. The view-model owns editing state. The view renders the view-model. Semantic wrappers only set kind and numeric defaults.

MVVM

flowchart LR
  Props["InputProps"] --> ViewModel["useInputViewModel"]
  Model["input.model.ts<br/>kind, parse, format"] --> ViewModel
  ViewModel --> View["Input.tsx"]
  Metadata["jo-ui-field-metadata"] --> View
  View -->|"focus, change, blur"| ViewModel
  ViewModel -->|"onValueChange"| Host["Host application"]
  ViewModel -->|"onParsedValueChange"| Host
  Wrappers["EmailInput and numeric wrappers"] --> View

| Layer | File | Responsibility | | --- | --- | --- | | Contract | input.types.ts | Kind, parsed value, props, and view-model | | Model | input.model.ts | Resolve kind behavior, parse text, and format on blur | | Model | textarea.model.ts | Textarea classes and controlRows | | View-model | input.view-model.ts | Framework-free input observable; own the draft while editing | | View | input.use-view-model.ts | useInputViewModel reads that observable and syncs a controlled value | | View-model | date-field.view-model.ts | Framework-free date-field observable | | View | date-field.use-view-model.ts | useDateFieldViewModel reads that observable | | View-model | textarea.view-model.ts | Framework-free textarea observable | | View | textarea.use-view-model.ts | useTextareaViewModel reads that observable | | View | Input.tsx | Render the field from the view-model | | View | DateField.tsx | Date input with the same height, radius, and label wiring | | View | Textarea.tsx | Multiline field with the same control metrics | | Shared metadata | @net-advantage/jo-ui-field-metadata | Lay out the label, helper text, required marker, and nested input | | Wrappers | semantic-inputs.tsx | Set kind for email, integer, decimal, percentage, and currency |

Models

flowchart TD
  Kind["InputKind"] --> Behavior["KindBehavior"]
  Kind --> Parsed["ParsedInputValue"]
  Behavior --> Presentation["NumericPresentation"]
  Props["InputProps"] --> ViewModel["InputViewModel"]
  Parsed --> ViewModel
  Presentation --> ViewModel

• InputKind is text, email, password, search, tel, url, integer, decimal, percentage, or currency.
• kind is the only behavior prop. InputField does not accept type. The DOM input type is derived from kind and is not a public prop.
• ParsedInputValue is a string, a number, or null.
• A controlled value is shown until the field is focused. While editing, the view-model keeps a draft. Blur formats that draft and leaves edit mode.
• parse and format override the kind parser and formatter. Omit them and the model uses the kind defaults.
• InputField, DateField, and Textarea require label or ariaLabel. A visible label is preferred and is referenced with aria-labelledby. ariaLabel is the control's aria-label when the field should not show a label. Passing neither is a compile error. The same contract applies to EmailInput, IntegerInput, DecimalInput, PercentageInput, and CurrencyInput. label may be any React node.
• labelPlacement accepts top or left; descriptionPlacement accepts below-label or below-control.
• Validation errors remain alerts below the input while ordinary helper text is rendered by FieldMetadata.
• fullWidth stretches a field. Inside FormLayout, fields are full width unless fullWidth is false. DateField and Textarea use the same control height and --jo-radius-control as the text input.

Semantic input strategy

Use one base control (InputField) and configure behavior with kind:

• text, email, password, search, tel, url
• integer, decimal, percentage, currency

InputField has no type prop. resolveKindBehavior derives the DOM type from kind. email, password, search, tel, and url keep that HTML type. text, integer, decimal, percentage, and currency use type="text".

Helpful props for semantic kinds:

• onParsedValueChange: emits parsed values (number, string, or null)
• parse: custom parser override
• format: custom formatter override
• locale, currency, minimumFractionDigits, maximumFractionDigits

Convenience wrappers are also exported:

• EmailInput
• IntegerInput
• DecimalInput
• PercentageInput
• CurrencyInput

Locale and currency

Resolved locale and currency follow this order:

1. The resolved locale is the locale prop when it is a non-empty string. Otherwise it is Intl.DateTimeFormat().resolvedOptions().locale.
2. The currency is the currency prop when it is a non-empty string. An explicit currency always wins. Otherwise the currency is the ISO 4217 code for that locale's region.
3. The region is Intl.Locale(locale).region. When that is missing, the region is new Intl.Locale(locale).maximize().region.
4. Regions map to currencies as follows: US USD, GB GBP, DE/FR/ES/IT/NL/IE/AT/BE/PT/FI EUR, JP JPY, CN CNY, CA CAD, AU AUD, NZ NZD, CH CHF, SE SEK, NO NOK, DK DKK, IN INR, BR BRL, MX MXN, KR KRW, SG SGD, HK HKD, ZA ZAR.
5. When the region is absent or unmapped, the currency symbol stays empty. The number is still formatted.

CurrencyInput does not default the currency to USD. Omit currency to use the locale currency.

Structure

• src: runtime component, model, view-model, and types.
• stories: Storybook stories for documentation and visual testing.

Publish footprint

This package publishes only:

• dist
• README.md

Stories and tests are excluded from the published artifact by design.