Update docs

spring-shell-docs/modules/ROOT/pages/components/ui/confirmation.adoc

@@ -0,0 +1,30 @@
+[[using-shell-components-ui-confirmation]]
+= Confirmation
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The confirmation component asks a user for a simple confirmation. It is essentially a
+yes-or-no question.
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet5]
+----
+
+The following image shows the typical output from a confirmation component:
+
+image::component-confirmation-1.svg[text input]
+
+The context object is `ConfirmationInputContext`. The following table describes its context variables:
+
+[[confirmationinputcontext-template-variables]]
+.ConfirmationInputContext Template Variables
+|===
+|Key |Description
+
+|`defaultValue`
+|The default value -- either `true` or `false`.
+
+|`model`
+|The parent context variables (see xref:components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
+|===

spring-shell-docs/modules/ROOT/pages/components/ui/index.adoc

@@ -0,0 +1,30 @@
+[[using-shell-components-ui]]
+= Flow Components
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+Starting from version 2.1.x, a new component model provides an
+easier way to create higher-level user interaction for the usual use cases,
+such as asking for input in various forms. These usually are just plain text
+input or choosing something from a list.
+
+Templates for built-in components are in the
+`org/springframework/shell/component` classpath.
+
+Built-in components generally follow this logic:
+
+. Enter a run loop for user input.
+. Generate component-related context.
+. Render the runtime status of a component state.
+. Exit.
+. Render the final status of a component state.
+
+NOTE: xref:components/flow/index.adoc[Flow] gives better interface for defining the flow of
+components that are better suited for defining interactive command flows.
+
+
+
+
+
+
+

spring-shell-docs/modules/ROOT/pages/components/ui/multiselect.adoc

@@ -0,0 +1,33 @@
+[[using-shell-components-ui-multiselect]]
+= Multi Select
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The multi select component asks a user to select multiple items from a list.
+The following listing shows an example:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet7]
+----
+
+The following image shows a typical multi-select component:
+
+image::component-multi-select-1.svg[text input]
+
+The context object is `MultiItemSelectorContext`. The following table describes its context variables:
+
+[[multiitemselectorcontext-template-variables]]
+.MultiItemSelectorContext Template Variables
+|===
+|Key |Description
+
+|`values`
+|The values returned when the component exists.
+
+|`rows`
+|The visible items, where rows contain maps of name, selected, on-row, and enabled items.
+
+|`model`
+|The parent context variables (see xref:components/ui/render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]).
+|===

spring-shell-docs/modules/ROOT/pages/components/ui/pathinput.adoc

@@ -0,0 +1,26 @@
+[[using-shell-components-ui-pathinput]]
+= Path Input
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The path input component asks a user for a `Path` and gives additional information about a path itself.
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet4]
+----
+
+The following image shows typical output from a path input component:
+
+image::component-path-input-1.svg[text input]
+
+The context object is `PathInputContext`. The following table describes its context variables:
+
+[[pathinputcontext-template-variables]]
+.PathInputContext Template Variables
+|===
+|Key |Description
+
+|`model`
+|The parent context variables (see xref:components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
+|===

spring-shell-docs/modules/ROOT/pages/components/ui/pathsearch.adoc

@@ -0,0 +1,34 @@
+[[using-shell-components-ui-pathsearch]]
+= Path Search
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The path search component asks base directory for scan and optional search expression.
+Results are shown in a single select list where user can pick a path.
+`PathSearchConfig` can be used to customise component behaviour.
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet9]
+----
+
+NOTE: Logic for search is passed as is into algorithms documented
+in xref:appendices-techical-intro-searchalgorithm.adoc[Search Algorithms].
+
+The following image shows typical output from a path search component:
+
+image::component-path-search-1.svg[text input]
+
+The context object is `PathSearchContext`. The following table describes its context variables:
+
+[[pathsearchcontext-template-variables]]
+.PathSearchContext Template Variables
+|===
+|Key |Description
+
+|`pathViewItems`
+|The items available for rendering search results.
+
+|`model`
+|The parent context variables (see xref:/components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
+|===

spring-shell-docs/modules/ROOT/pages/components/ui/render.adoc

@@ -0,0 +1,99 @@
+[[using-shell-components-ui-render]]
+= Component Render
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+You can implement component rendering in either of two ways: fully
+programmatically or by using a _ANTLR Stringtemplate_.
+Strictly speaking, there is a simple `Function` renderer interface
+that takes `Context` as an input and outputs a list of `AttributedString`.
+This lets you choose between templating and code.
+
+Templating is a good choice if you do not need to do anything complex or
+you just want to slightly modify existing component layouts. Rendering
+through code then gives you flexibility to do whatever you need.
+
+The programmatic way to render is to create a `Function`:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet1]
+----
+
+Then you can hook it to a component:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet2]
+----
+
+Components have their own context but usually share some functionality
+from a parent component types. The following tables show those context variables:
+
+[[textcomponentcontext-template-variables]]
+.TextComponentContext Template Variables
+|===
+|Key |Description
+
+|`resultValue`
+|The value after a component renders its result.
+
+|`name`
+|The name of a component -- that is, its title.
+
+|`message`
+|The possible message set for a component.
+
+|`messageLevel`
+|The level of a message -- one of `INFO`, `WARN`, or `ERROR`.
+
+|`hasMessageLevelInfo`
+|Return `true` if level is `INFO`. Otherwise, false.
+
+|`hasMessageLevelWarn`
+|Return `true` if level is `WARN`. Otherwise, false.
+
+|`hasMessageLevelError`
+|Return `true` if level is `ERROR`. Otherwise, false.
+
+|`input`
+|The raw user input.
+
+|===
+
+
+[[selectorcomponentcontext-template-variables]]
+.SelectorComponentContext Template Variables
+|===
+|Key |Description
+
+|`name`
+|The name of a component -- that is, its title.
+
+|`input`
+|The raw user input -- mostly used for filtering.
+
+|`itemStates`
+|The full list of item states.
+
+|`itemStateView`
+|The visible list of item states.
+
+|`isResult`
+|Return `true` if the context is in a result mode.
+
+|`cursorRow`
+|The current cursor row in a selector.
+
+|===
+
+
+[[componentcontext-template-variables]]
+.ComponentContext Template Variables
+|===
+|Key |Description
+
+|`terminalWidth`
+|The width of terminal, type is _Integer_ and defaults to _NULL_ if not set.
+
+|===

spring-shell-docs/modules/ROOT/pages/components/ui/singleselect.adoc

@@ -0,0 +1,42 @@
+[[using-shell-components-ui-singleselect]]
+= Single Select
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+A single select component asks a user to choose one item from a list. It is similar to a simple
+dropbox implementation. The following listing shows an example:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet6]
+----
+
+The following image shows typical output for a single select component:
+
+image::component-single-select-1.svg[text input]
+
+The context object is `SingleItemSelectorContext`. The following table describes its context variables:
+
+[[singleitemselectorcontext-template-variables]]
+.SingleItemSelectorContext Template Variables
+|===
+|Key |Description
+
+|`value`
+|The returned value when the component exists.
+
+|`rows`
+|The visible items, where rows contains maps of name and selected items.
+
+|`model`
+|The parent context variables (see xref:/components/ui/render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]).
+|===
+
+You can pre-select an item by defining it to get exposed. This is
+useful if you know the default and lets the user merely press `Enter` to make a choice.
+The following listing sets a default:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet8]
+----

spring-shell-docs/modules/ROOT/pages/components/ui/stringinput.adoc

@@ -0,0 +1,42 @@
+[[using-shell-components-ui-stringinput]]
+= String Input
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The string input component asks a user for simple text input, optionally masking values
+if the content contains something sensitive. The following listing shows an example:
+
+[source, java, indent=0]
+----
+include::{snippets}/UiComponentSnippets.java[tag=snippet3]
+----
+
+The following image shows typical output from a string input component:
+
+image::component-text-input-1.svg[text input]
+
+The context object is `StringInputContext`. The following table lists its context variables:
+
+[[stringinputcontext-template-variables]]
+.StringInputContext Template Variables
+|===
+|Key |Description
+
+|`defaultValue`
+|The default value, if set. Otherwise, null.
+
+|`maskedInput`
+|The masked input value
+
+|`maskedResultValue`
+|The masked result value
+
+|`maskCharacter`
+|The mask character, if set. Otherwise, null.
+
+|`hasMaskCharacter`
+|`true` if a mask character is set. Otherwise, false.
+
+|`model`
+|The parent context variables (see xref:/components/ui/render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
+|===