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

Color swatch selector with fixed 32px swatches and an optional add-color chooser.

The swatch follows a strict MVVM split. The model decides which colors are visible and how a chosen color is applied. The view-model owns selection and the chooser. The view renders the view-model and hosts ColorPicker for the draft color.

MVVM

flowchart LR
  Props["ColorSwatchProps"] --> ViewModel["useColorSwatchViewModel"]
  Model["color-swatch.model.ts<br/>visible colors and apply"] --> ViewModel
  ViewModel --> View["ColorSwatch.tsx"]
  Metadata["jo-ui-field-metadata"] --> View
  View -->|"select or apply"| ViewModel
  ViewModel -->|"onValueChange"| Host["Host application"]
  Picker["jo-ui-color-picker"] -->|"draft color"| View

| Layer | File | Responsibility | | --- | --- | --- | | Contract | color-swatch.types.ts | Props and view-model | | Model | color-swatch.model.ts | Clamp the visible list and apply a chosen color | | View-model | color-swatch.view-model.ts | Framework-free color swatch observable; own selection, remaining colors, and the chooser | | View | color-swatch.use-view-model.ts | useColorSwatchViewModel reads that observable and owns palette sync and outside-click effects | | View | ColorSwatch.tsx | Render swatches and the chooser from the view-model | | Shared metadata | @net-advantage/jo-ui-field-metadata | Render the label, helper text, spacing, and association IDs |

Models

flowchart TD
  Color["RGB color string"] --> Visible["visible swatches"]
  Color --> Remaining["remaining colors"]
  Visible --> Applied["AppliedSwatch"]
  Remaining --> Applied
  Applied --> ItemVm["ColorSwatchItemViewModel"]
  ItemVm --> ViewModel["ColorSwatchViewModel"]

• colors and optionalColors are arrays of RGB color strings, such as #1E2A5A.
• maxVisibleColors limits the first paint. singleColorSelection keeps one visible swatch.
• AppliedSwatch is the result of choosing a color. In single mode it updates that swatch. A color already visible is selected and is not added again. Otherwise it is appended and removed from the remaining list.
• If value is not visible, it is promoted into colors; the last visible color moves to optionalColors so the selected value remains available.
• The chooser is a menu. Its apply label is Apply Color in single mode and Add Color otherwise.
• label or ariaLabel is required. A visible label is preferred and names the radio group through aria-labelledby. ariaLabel is the group's aria-label when the swatch should not show a label. Passing neither is a compile error. A caller that bypasses the type and passes neither still sees ACCENT COLOUR.
• Composite label and helper rendering comes from FieldMetadata; the swatch does not own duplicate metadata selectors.
• labelPlacement accepts top or left; descriptionPlacement accepts below-label or below-control.

Features

• Displays a selectable color swatch list
• Supports optional color list added through a reusable color picker chooser
• maxVisibleColors prop controls how many colors are shown
• 32px swatch tiles to match Journey admin controls

Structure

• src: runtime component, model, view-model, default colors, and styles
• stories: Storybook stories for docs and visual testing

Publish footprint

This package publishes only:

• dist
• README.md