Illustrating a setting

“Carry over the item number” is a sentence you only understand after trying it. So a boolean or a select can declare an example: one case per choice, each with the quote lines that choice produces. The panel draws them side by side and lights the one matching the current value.

Both panels below are live: tick the box, change the dropdown.

Carry over the item numberWrites the number of the original item, useful when the client compares documents.

Without reference

Dettaglio servizi

#	Servizio	Qtà	Totale
01	Plasterboard ceiling Steel frame, 12.5 mm board	68,4 mq	1.915,20 €

With reference

Dettaglio servizi

#	Servizio	Qtà	Totale
01	Plasterboard ceiling (item 12.4 of the bill) Steel frame, 12.5 mm board	68,4 mq	1.915,20 €

const CEILING = { detail: "Steel frame, 12.5 mm board", qty: 68.4, unit: "mq", price: 28 };
const WORK = "Plasterboard ceiling";

{
  key: "showReference",
  type: "boolean",
  label: "Carry over the item number",
  default: true,
  example: {
    kind: "quoteLines",
    cases: [
      { when: false, label: "Without reference",
        lines: [{ ...CEILING, description: WORK }] },
      { when: true, label: "With reference",
        lines: [{ ...CEILING, description: [WORK, { mark: " (item 12.4 of the bill)" }] }] },
    ],
  },
}

when

The value that case illustrates, exactly like equals in visibleWhen.

The cases must cover every choice of the field — both positions of a switch, every option of a select — and definePlugin insists on it: the choice left out would light nothing when picked, and whoever picks it would be staring at somebody else’s example. A select with nine options simply doesn’t get illustrated, and that’s the right answer rather than a wall of cards.

mark

description and detail take a string, or a list of pieces where { mark } is the highlighted one. Two descriptions differing by four words are told apart by nobody.

description: [WORK, { mark: " (item 12.4)" }]        // trailing
description: [{ mark: "Ref. 12.4 — " }, WORK]        // leading
description: ["Ceiling ", { mark: "(rif. 12.4) " }, "in plasterboard"]

The piece goes wherever you put it, and there is no string to keep in sync by hand: the highlight is the piece, rather than a pointer into the text.

More than two choices

How to word the items

Plain

Dettaglio servizi

#	Servizio	Totale
01	Ceiling	1.915,20 €

Standard

Dettaglio servizi

#	Servizio	Totale
01	Plasterboard ceiling Steel frame, 12.5 mm board	1.915,20 €

Specification

Dettaglio servizi

#	Servizio	Totale
01	Ceiling in 12.5 mm gypsum board — EN 520 Galvanised frame 27/48 at 600 mm centres, joints filled to level Q2	1.915,20 €

How far to go into materials and workmanship.

Two cases sit side by side, three go three across, four or more wrap onto two columns. From three up the table drops the quantity column: in a third of the width, four columns stop being readable.

For a select the caption above each card comes from the option’s own label, so label is only for saying something different from the dropdown.

What it can’t do for you

The example is written by hand and nothing checks that it matches what the model actually produces. It lives in the same file as the prompt for that reason: whoever changes the prompt updates the example. An illustration that promises one thing while the assistant does another is worse than no illustration.

multiselect, number and text can’t be illustrated: a set of values or a free number doesn’t map onto a list of cases, and when would have nothing to hold.