diy-layout-creator/diylc/docs/plans/rkm-value-notation.md

RKM Value Notation for Resistance and Capacitance

Let users read and type resistor and capacitor values in RKM (IEC 60062) notation, where the unit letter replaces the decimal point (4K7, 0R22, 2n2, 0u22), as well as in today's decimal form (4.7K, 0.22uF). Typing a value with a unit letter in it, in either notation, also sets the unit, so 4K7 typed into a field whose unit is Ω becomes 4.7 K.

1. User-facing behaviour

Config menu

One radio submenu in ConfigPlugin covering both resistance and capacitance, built the same way as Snap To and Ruler Inch Subdivision... (ToggleAction, string config key, title stored as the value):

Config
  ...
  Value Notation >            (after Sticky Points, alphabetical like the rest)
      (o) Decimal (4.7K, 0.22uF)
      ( ) RKM (4K7, 0u22)
  ...

• Key IPlugInPort.VALUE_NOTATION_KEY = "valueNotation", values VALUE_NOTATION_DECIMAL / VALUE_NOTATION_RKM, default decimal.
• Switching notation repaints the canvas immediately, so labels on the board change at once.

What the notation controls (display)

The notation governs Resistance.toString() and Capacitance.toString() and therefore everything built on them: labels drawn on the canvas, getValueForDisplay() (search, BOM, netlist text, project explorer, AI assistant context). The edit dialog's value field is the exception: it always shows the bare decimal number, because the unit box beside it already carries the unit and an RKM code there would repeat it.

Value	Decimal (unchanged)	RKM
4.7 Ω	4.7Ω	4R7
0.22 Ω	0.22Ω	0R22
100 Ω	100Ω	100R
4.7 K	4.7K	4K7
47 K	47K	47K
1 M	1M	1M
0.22 uF	0.22uF	0u22
2.2 nF	2.2nF	2n2
100 nF	100nF	100n
4.7 pF	4.7pF	4p7
1000 uF	1000uF	1000u

Rules: RKM keeps the stored unit (it never renormalises 4700 Ω to 4K7), uses R for ohms, drops the trailing F on capacitance, puts the unit letter where the decimal point was, and writes it as a suffix for whole numbers. The digits after the letter are rounded the same way as today's 0.#### decimal format.

What the user can type (input)

The value field accepts, in both notations:

• a bare number (4.7, 0,22) — the unit is unchanged, as today;
• a decimal number with a unit (4.7k, 0.22uF, 220 nF, 4.7ohm, 4.7Ω);
• an RKM code (4K7, 4k7, 0R22, R22, 2n2, 0u22, 4µ7, 1M, 100R).

When the text carries a unit, the unit combo switches to it and the property gets the new value and unit together. Accepted unit letters, case-insensitive except where noted:

• Resistance: R, Ω, ohm/ohms → Ω; K/k → K; M/m/Meg → M (there is no milliohm unit, so a lower-case m on a resistor means mega, as it does on many parts lists).
• Capacitance: p → pF; n → nF; u/µ → uF; m → mF (case-sensitive: M is not accepted, to avoid reading "mega"); F alone → F. A trailing F after any of these is optional (4u7F, 2.2nF).

A unit letter that does not belong to the measure (4u7 on a resistor) shows the existing warning icon, as any unparseable text does today.

Commit behaviour. The property is updated on every keystroke, as today — the edit dialog's Enter key commits straight away, so it cannot wait for focus loss. When the field loses focus, the text is rewritten as the bare decimal number (4K7 typed → 4.7 with the combo showing K), whichever notation is selected. The text is not reformatted while the user is typing, so the caret never jumps.

2. Design

Core (diylc-core, org.diylc.core.measures)

• ValueNotation — new enum DECIMAL, RKM holding the formatting and parsing logic, so the two measure classes stay thin:
  • String format(double value, Unit unit, String rkmSymbol) — decimal falls through to the existing 0.#### + unit.toString(); RKM implements the rules in §1.
  • static ParsedMeasure parse(String text, ...) — returns value + unit (unit null for a bare number), or throws IllegalArgumentException. One small record ParsedMeasure<U> at the bottom of the file.
• Current notation. One private static volatile ValueNotation current on ValueNotation with static getCurrent() / setCurrent(), shared by Resistance and Capacitance. toString() reads the field, never ConfigurationManager: it runs from draw() on every repaint. Default DECIMAL, so headless rendering, the regression suite and unit tests are unchanged unless they opt in.
• Unit display symbol for RKM. ResistanceUnit and CapacitanceUnit get an rkmSymbol constructor argument (R/K/M, p/n/u/m/F). Enum constant names and toString() are untouched — XStream stores the constant name, so files are unaffected.
• Parsing. Resistance.parseResistance / Capacitance.parseCapacitance delegate to ValueNotation.parse, so RKM is accepted everywhere a string is turned into a value: the editor, V1FileParser, TangoNetlistParser, CapacitorDatasheetService and — important once toString() can emit 4K7 — the AI assistant, which receives values as text and writes them back through these parsers. Existing accepted inputs must keep parsing identically.
• Inductance and Power are out of scope; their names are left as they are.

Wiring the setting

org.diylc.presenter.ValueNotationBinder.bind(configManager, refresh) reads the key once, pushes it into ValueNotation.setCurrent(), and on change updates the static, calls DrawingCache.Instance.clear() (cached component images contain the old labels) and refreshes the canvas. It is called from ConfigPlugin.connect(), not from the Presenter constructor: the notation is global, and the many secondary presenters (project preview, cloud thumbnails, batch converter, regression runner) are built on in-memory configurations and would reset it to decimal.

Swing (diylc-swing)

• MeasureTextField — new field in org.diylc.swing.gui.editor, beside MeasureEditor. Same look as DoubleTextField (warning icon on the right) but it parses through ValueNotation.parse for the measure type and fires a MEASURE_PROPERTY change carrying value + optional unit; on focusLost it reformats its text. It is generic over the unit enum so it can serve Inductance later without changes.

  Recommendation: keep it in DIYLC rather than extending DoubleTextField in bancika-gui-framework. The framework is consumed as the vendored lib/swing-framework-1.1.jar, so a change there means rebuilding and re-vendoring the jar for a widget whose parsing rules are DIYLC domain knowledge. DoubleTextField keeps serving PercentageEditor, LoadlineEditorFrame and every other plain-number measure.

  One DoubleTextField bug is worth fixing in the framework separately, and the new field must not copy it: DecimalFormat.parseObject(String) accepts a valid prefix, so 4R7 silently parses as 4 today, with no warning.

• MeasureEditor — uses MeasureTextField when the property type is Resistance or Capacitance, DoubleTextField otherwise. On a value + unit event it sets the combo's selected unit behind a guard flag, so the combo's own ActionListener does not fire a second setValue. Read-only properties keep today's behaviour (disabled field, combo converts).

• MeasureArrayEditor (MultiSectionCapacitor) — each section value is parsed with the same rules. Units travel per section in the text (47u / 22u / 10u) and a section without a unit takes the combo's unit, as today. The combo shows the first section's unit; in decimal notation a section in a different unit is written with its unit (47 / 100nF). Changing the combo applies its unit to every section, as before.

• ConfigPlugin — the Value Notation submenu (IconLoader.Decimal), and the call to ValueNotationBinder.bind.

Localization

New keys in English.txt and every other file in lang/: Value Notation, Decimal (4.7K, 0.22uF), RKM (4K7, 0u22). Because ToggleAction stores its title as the config value, the stored values are the English titles and MainFrame translates only what is shown.

3. Compatibility

• .diy files store value and the unit enum name; neither changes. No serialization impact.
• With the default (decimal) every string the app produces is byte-identical to today, so regression references do not move. A regression run is still worth doing after implementation, since parseResistance / parseCapacitance change.
• A user who switches to RKM gets RKM in BOM and netlist exports as well. That is the intended "everywhere" behaviour; anything that re-imports those files goes through the RKM-aware parsers.

4. Tests (diylc-core, JUnit 4)

ValueNotationTest:

• formatting: every row of the §1 table, both notations; zero, null, values ≥ 1000 in their unit, rounding at the fourth decimal;
• parsing: every input form in §1, per measure; case rules (m vs M for capacitance); comma as decimal separator; rejects 4u7 on a resistor, 4K7K, K, empty text;
• round trip: parse(format(x)) returns x for both notations;
• regression guard: every string currently accepted by parseResistance / parseCapacitance (the inputs in V1FileParser, TangoNetlistParser and CapacitorDatasheetService tests and AiEditScriptEditorTest) still parses to the same value.

5. Status and next steps

Implemented as described; mvn -q test passes, including ValueNotationTest.

1. Try it in the running app: the edit dialog (single value and MultiSectionCapacitor), canvas labels after switching notation, BOM export.
2. Run the regression suite to confirm decimal output is unchanged.
3. Optional, in bancika-gui-framework: stop DoubleTextField / DoubleArrayTextField accepting a valid prefix (4R7 read as 4).