| :warn: this page is under construction.

## Purpose
The Inputs Initiative is a collaborative effort to ensure all Kudamono Editor interactions are: 
- **tailored to each genre** (the best input modes and aux marks were picked) and **frictionless**, via comprehensive auto-modes that  minimise switching
- **intuitive** via //sensible defaults// and **consistent across genres** (learn once, use everywhere)
- **accessible** (fully functional under restricted controls, such as touchscreen-only, keyboard-only, mouse-only)
- **always correct**, despite regular updates

Doing so requires cross-genre:
- [#input unit tests], to register the desired result for well-chosen interaction sequences
- [#input configurations], through which the desired input modes can be totally expressed :::TBA

With these two pieces, all users will be empowered to:
- specify a preferred configuration unambiguously, for every genre;
- share configurations (and propose defaults);
- send a input unit test for inclusion in the system, so it starts (or continues) to work as expected;
- check system status independently for (un)known input bugs


## Input Unit tests

Each input unit test has tree fields: [#from], [#to] and [#via], placed like in this example:

´´´
	from:"W=1x1",
	to:"W=1x1&LF=z0",
	via:[{CL:[[0,0]]}]
´´´

Each field is explained now:

### From

The initial state is represented in the ´´from´´ field. 
It is the current board **before** any interaction takes place, expressed as a reduced puzzle url (just the part after the question mark) between quotes.

The simplest possible ´´from´´ field represents an empty, a single-cell 1x1 board:
´´from:"W=1x1"´´

| :info: The starting board should be the smallest possible, to increase testing speed when thousands of tests are run at once.


### To

The final state is represented in the ´´to´´ field. 
It is the current board **after** all interactions took place, expressed as a reduced puzzle url.

Let's say we wish to place, on that same 1x1 board, a shaded cell. Thus we obtain:
´´to:"W=1x1&LF=z0"´´

|:info: for convenience, pressing [[shift c]] copies the current reduced board url


### Via

The via field stores the sequence of interactions that transform the initial into the final state.

In our example, we wish to perform a sequence of a single left-click (CL) [#action] to place a shaded cell on the leftmost, bottom cell ([#coordinates] [0,0])
´´via:[{CL:[[0,0]]}]´´


#### Actions

VIA 	TYPE		BUTTON
CL		**C**lick	**L**eft mouse button
CR		**C**lick	**R**ight mouse button
CM		**C**lick	**M**iddle mouse button
CT		**C**lick	**T**ouchscreen (one finger-tap)
DL		**D**rag	**L**eft mouse button
DR		**D**rag	**R**ight mouse button
DM		**D**rag	**M**iddle mouse button
DT		**D**rag	**T**ouchscreen (one finger-drag)
K		**K**ey		*K*eyboard key(s), e.g. ´´A´´, ´´spacebar´´, ´´ctrl shift del´´

More actions may be added in the future, as needed.


#### Coordinates for click/drag actions

In the square grid, standard cartesian coordinates are used, with origin at the centre of the bottom left cell.

images/input/coordinate-centers.png
((cartesian coordinates example grid))

Zooming in on the origin cell, we can see that with fractional coordinates can be used to specify any point, such as tile corners and tile edge midpoints.

images/input/coordinate-intile.png
((fractional coordinates illustration))



## Input Configurations

| :warn: this section is outdated, a simpler version is coming.


A [#configuration object] specifies all possible interactions, depending on:
- which mode is active (solve or edit)
- which [#input modality] was picked (from button click or keyboard shortcuts, possibly auto) 
- which [#placement] was selected (from first touched tile)


### Placements

Known placement names:
- **tile** (centre)
- **corner**
- **edge** (midpoint)
- **diag** (points halfway between tile centre and each corner)
- **ortho** (points halfway between tile centre and each edge midpoint)

Note that these points are independent of geometry.
There will be a way to name supplementary placements (e.g knight points, circulars) where needed.


### Input modality

An input modality maps [#actions] to [#composite changes]

### Atomic changes

Atomic changes are not divisible. 

Erase: erases the selected item, if there.
- erase-segment
- erase-sketch
- erase-symbol
- erase-auxmark

Add: adds the selected item, if not yet there.
- add-segment
- add-sketch
- add-symbol
- add-auxmark


### Composite changes

Composite changes are divisible. They can contain atomic changes and other composite changes.

Replace family: adds the selected item, erasing other conflicting items in the same layer, or erases the selected item if already there
- replace-segment
- replace-sketch
- replace-symbol
- replace-auxmark

Cycle family: successively replaces the selected item from a list of possibilities. At the end of the cycle, erases the last item.
- cycle-segment
- cycle-sketch
- cycle-symbol
- cycle-auxmark

Specials:
-replace-direline: replace-segment and add-symbol-arrowhead to last line segment, erasing others in the (connected long-) line 
-replace-numerline: add a sequence of numbers or erase
-replace-number-polar: add-symbol number, increment or decrement existing number by a certain numebr of steps, erase number if increment is zero 

Options:
- line compass
- line free or not
- line figure (square, rectangle, radial,....)
- movement line




### Configuration Object


´´´´´´´´
{
	"solve":{
		"line":{
			"tile":{
				CL:"toggle-segment",
				CR:"cycle-auxmark-tile",
				CT:"toggle-segment",
				DL:"drag-segment",
				DR:"drag-sketch",
				DT:"drag-segment",
			},
			"edge":{
				CL:"toggle-segment",
				CR:"cycle-auxmark-edge",
				CT:"toggle-segment",
				DL:"drag-segment",
				DR:"drag-sketch",
				DT:"drag-segment",
			},
		},
		"aux-mark-o":{
			"tile":{
				CL:"toggle-auxmark:o",
				CR:"erase-auxmark:o",
				CT:"toggle-auxmark:o",
				DL:"drag-auxmark:o",
				DR:"drag-erase-auxmark:o",
				DT:"drag-auxmark:o",
			},
		},
		"aux-mark-e":{
			"edge":{
				CL:"toggle-auxmark:e",
				CR:"erase-auxmark:e",
				CT:"toggle-auxmark:e",
				DL:"drag-auxmark:e",
				DR:"drag-erase-auxmark:e",
				DT:"drag-auxmark:e",
			},
		},
		"sketch":{
			"tile":{
				CL:"toggle-sketch",
				CR:"cycle-auxmark-tile",
				CT:"toggle-sketch",
				DL:"drag-sketch",
				DR:"drag-segment",
				DT:"drag-sketch",
			},
			"edge":{
				CL:"toggle-segment",
				CR:"cycle-auxmark-edge",
				CT:"toggle-segment",
				DL:"drag-segment",
				DR:"drag-sketch",
				DT:"drag-segment",
			},
		}
	},
	edit:{
		"number-polar":{
			"tile":{
				CL:"erase-number",
				CR:"toggle-auxmark:o",
				CT:"erase-number",
				DL:"polar-number",
				DR:"drag-auxmark:o",
				DT:"polar-number",
			},
		},
		"absent-tile":{
			"tile":{
				CL:"toggle-symbol:x",
				CR:"erase-symbol:x",
				CT:"toggle-symbol:x",
				DL:"drag-symbol:x",
				DR:"drag-erase-symbol:x",
				DT:"drag-symbol:x",
			},
		},
		"aux-mark-o":{
			// (same as in solve)
		},
		"aux-mark-e":{
			// (same as in solve)
		},
		"sketch":{
			// (same as in solve)
		}
	}
}
´´´´´´



## Changes
**2023-04-12** Preliminary draft page for the [Inputs Initiative].


id			kudamono/inputs
title		Inputs Initiative
summary		The Inputs Initiative is a collaborative effort to ensure all Kudamono Editor interactions are genre-tailored, frictionless, intuitive, accessible and correct. It relies on Input Unit Tests and Input Configurations.
tags		Kudamono, Docs, Software, Collaboration
date		2024-04-12
slug		inputs
folder		kudamono
imageName	kudamono-inputs-initiative
template	postlike, kuda-navo
type		Post
typegraph	article
dated		true
toced		true
feather		PostFeatherl
body		()=>Bodyl("classic")
footer		()=>Footerl()
author		Pedro
imageExt	png
themecolour	rgb(7,0,112)
opensearch	all
path		()=>BiPath(Settings.site.url,UrlRelativedPath(AtUrl()))
navo		{'Projects':'projects.html','Contacts':'contacts.html','All':'tag.html'}




// Every input mode must have a corresponding button.
// No information may be implicit
// Keyboard shortcuts do not matter, too much as they are seen primarily as a means to select a particular input mode rather than performing the input. In very specific cases, selected keyboard key combos could be added as extra modalities (in addition to those 6 above).
// Input modes in edit or solve mode are seen as distinct; though they can point towards the same actions where needed.


// Maybe this...  (< means "is contained in" )
// (1) atomic change < (2) composite change < (3) placement-dependent change < (4) contextual change / modality <  (5) input mode < (6) configuration



// Examples of input modes:
// - auto-mode in RB Loop (line + shade):
//     - CL: shade cell, remove shade,  
//     - CT: shade cell, place unshade mark and remove shade, remove unshade mark
//     - CR: unshade mark, remove unshade mark; on edge place cross, remove cross 
//     - DL: draw line, erase line
//    - DR: sketch
//    - DT: draw line, erase line


// *End of rubber duck ramble*
// :first_quarter_moon_with_face: