registry: RangeController, ModeController, ToggleController with resources, presets and semantics

The three generic controllers are described in full and leave the stub table (62 stubs remain). A declaration
takes an instance name, friendly names from text() and asset(), and the options of the interface: range, unit and
presets for a range; supportedModes and ordered for a mode; semantics() for all three, with actions mapped to
directives and states mapped to a value or a range of values.

Refused at device.add(), each with the endpoint, interface and instance in the message: no instance name or no
friendly name; an instance declared twice; a first friendly name or a phrase used by another capability of the
endpoint; a reserved word, an asset id that is not in the catalog; range.max not above range.min; a preset off the
precision grid or outside the range; fewer than two modes or a mode listed twice; a mapping to a directive the
interface does not have, to a payload that does not fit, to a mode that is not listed, to AdjustMode on modes
that are not ordered; SetEcoOn, SetEcoOff, EcoOn and EcoOff on anything but a toggle.

For 1.x callers: Alexa.RangeController lists rangeValue (1.5.2 sent supported: []); addSupportedModes() announces
a mode given as a string as { value } and notes it, and takes { ordered: false } as a second argument, the default
stays true as 1.5.2 sent it (device.add() defaults to false). Declared the 1.x way, the zoo fan and curtain give
the same JSON as before.

Tests: the zoo blind, whose range, unit and semantics were written by hand into the JSON of 1.5.2, is declared
with device.add() and equals that JSON plus the Alexa capability; five capability objects of Amazon's examples
are reproduced the same way. 27 examples of four pages added. npm test: 108 pass (was 85) in 10.5-11.3 s, also on
Node 18.20.8 and 20.20.2.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

test/fixtures/types.ts

@@ -3,7 +3,7 @@
 // declaration stops rejecting what follows it.
 import {
   ActionMapping, AlexaActions, AlexaInterfaceType, Assets, BrightnessController, DeclarationError, DisplayCategory, EndpointHealth,
-  PowerController, PowerState, TemperatureSensor, asset, registry, text,
+  ModeController, PowerController, PowerState, RangeController, TemperatureSensor, ToggleController, asset, registry, semantics, text,
 } from "alex2node";
 import type {
   Alex2MQTT, Alex2MQTTOptions, AlexaInterface, AlexaStatusMessage, AssetId, Capability, CapabilityJson, ChangeCause, Device,
@@ -74,6 +74,44 @@ const names: Label[] = [asset("Alexa.Setting.Opening"), text("Position"), text("
 // @ts-expect-error not in the global Alexa catalog
 asset("Alexa.Setting.Openning");
 
+// The generic controllers: an instance name, friendly names and the options of the interface
+const lift = blinds.add(RangeController, {
+  instance: "Blind.Lift",
+  friendlyNames: names,
+  range: { min: 0, max: 100, precision: 1 },
+  unit: "Alexa.Unit.Percent",
+  presets: [{ value: 100, friendlyNames: [asset("Alexa.Value.Maximum")] }],
+  semantics: semantics()
+    .action("Close", "SetRangeValue", { rangeValue: 0 })
+    .action(["Open", AlexaActions.Raise], "SetRangeValue", { rangeValue: 100 })
+    .state("Closed", 0)
+    .stateRange("Open", 1, 100),
+  retrievable: true,
+  proactivelyReported: true,
+});
+blinds.add(ModeController, {
+  instance: "Blind.Position",
+  friendlyNames: [text("Position")],
+  supportedModes: [{ value: "Position.Up", friendlyNames: [asset("Alexa.Value.Open")] }, { value: "Position.Down", friendlyNames: [asset("Alexa.Value.Close")] }],
+  ordered: false,
+});
+blinds.add(ToggleController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")], nonControllable: true });
+// @ts-expect-error a range controller has a range
+blinds.add(RangeController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")] });
+// @ts-expect-error a generic controller has an instance name and friendly names
+blinds.add(ToggleController, { proactivelyReported: true });
+// @ts-expect-error and so it cannot be declared without options
+blinds.add(ToggleController);
+// @ts-expect-error not a unit of measure
+blinds.add(RangeController, { instance: "Blind.Tilt", friendlyNames: [text("Tilt")], range: { min: 0, max: 90, precision: 1 }, unit: "Alexa.Unit.Percentage" });
+// @ts-expect-error not a phrase Alexa has
+semantics().action("Shut", "TurnOff");
+// What a directive carries and what a property holds are typed by the descriptor
+const lower: Infer<typeof RangeController.directives.AdjustRangeValue.payload> = { rangeValueDelta: -10, rangeValueDeltaDefault: false };
+const position: Schema<number> = lift.descriptor.properties.rangeValue.value;
+// @ts-expect-error a mode is a string, or null when none is set
+const current: Infer<typeof ModeController.properties.mode.value> = 3;
+
 // The registry: a descriptor by its namespace or by the 1.x enum member
 const described: InterfaceDescriptor = registry.get("Alexa.PowerController");
 const version: string = registry.get(AlexaInterfaceType.ENDPOINT_HEALTH).version;
@@ -95,6 +133,6 @@ const measured: Infer<typeof temperature> = { value: 20, scale: "CELSIUS" };
 const rankine: Infer<typeof temperature> = { value: 20, scale: "RANKINE" };
 
 export {
-  options, added, chained, sent, on, namespace, reachable, announced, endpoint, problems, names, version, refused, opening,
-  percent, vacuum, misspelt, notAUnit, measured, rankine,
+  options, added, chained, sent, on, namespace, reachable, announced, endpoint, problems, names, lower, position, current, version,
+  refused, opening, percent, vacuum, misspelt, notAUnit, measured, rankine,
 };