@net-advantage/jo-ui-color-picker

Compact labeled color selection control with helper text, a saturation and brightness surface, hue slider, and hex field.

The picker follows a strict MVVM split. The model owns color math. The view-model owns the current color, hex draft, and pointer sampling. The view renders the view-model.

MVVM

flowchart LR
  Props["ColorPickerProps"] --> ViewModel["useColorPickerViewModel"]
  Model["color-picker.model.ts<br/>hex and HSV"] --> ViewModel
  ViewModel --> View["ColorPicker.tsx"]
  Metadata["jo-ui-field-metadata"] --> View
  View -->|"surface, hue, hex"| ViewModel
  ViewModel -->|"onValueChange"| Host["Host application"]

| Layer | File | Responsibility | | --- | --- | --- | | Contract | color-picker.types.ts | Props and view-model | | Model | color-picker.model.ts | Convert hex and HSV and map pointer positions | | View-model | color-picker.view-model.ts | Framework-free color picker observable; own value, draft, sampling, and eyedropper | | View | color-picker.use-view-model.ts | useColorPickerViewModel reads that observable and syncs the hex draft | | View | ColorPicker.tsx | Render the stage from the view-model | | Shared metadata | @net-advantage/jo-ui-field-metadata | Render the label, helper text, spacing, and association IDs |

Models

flowchart TD
  Hex["hex string"] --> Hsv["HsvColor"]
  Hsv --> Hex
  Props["ColorPickerProps"] --> ViewModel["ColorPickerViewModel"]
  Hsv --> ViewModel

• HsvColor is hue, saturation, and value. Hue is 0 to 360. Saturation and value are 0 to 1.
• label or ariaLabel is required. A visible label is preferred and names the group. ariaLabel is the group's aria-label when the picker should not show a label. Passing neither is a compile error. A caller that bypasses the type and passes neither still sees the visible label COLOR. helperText still defaults to the gradient and hue guidance.
• Composite label and helper rendering comes from FieldMetadata; the color picker does not own duplicate metadata selectors.
• labelPlacement accepts top or left; descriptionPlacement accepts below-label or below-control.
• A valid hex is committed in uppercase. An invalid hex stays in the draft until blur, then the draft resets to the current color.
• The eyedropper is disabled unless EyeDropper is a function.

Structure

• src: runtime component, model, view-model, and types.

Features

• Saturation and brightness gradient
• Hue slider
• JO UI hex input for direct value entry
• Controlled and uncontrolled value support

Publish footprint

• dist
• README.md