Add READMEs explaining intent of library subdirs

Author: japhb

lib/Terminal/Widgets/I18N/README.md

@@ -0,0 +1,4 @@
+# Internationalization (I18N) Modules
+
+This directory contains modules, classes, and operators that power the I18N
+engine, such as string translation and locale sensitivity.

lib/Terminal/Widgets/Input/README.md

@@ -0,0 +1,7 @@
+# Input Widgets
+
+This directory contains all widgets primarily intended as inputs, such as
+classic form elements and editors.
+
+If the widget provides an interactive view but is _not_ intended primarily for
+input/editing, it probably belongs in `Viewer/` or `Viz/` instead.

lib/Terminal/Widgets/Layout/README.md

@@ -0,0 +1,4 @@
+# Layout Engine Modules
+
+This directory contains modules used to support the overall layout engine, such
+as the box model and its related calculations.

lib/Terminal/Widgets/Progress/README.md

@@ -0,0 +1,6 @@
+# Progress Widgets
+
+This directory contains widgets that primarily act as progress trackers, plus
+the `Terminal::Widgets::Progress::Tracker` role they share.
+
+Examples here would be progress bars, throbbers, job status trackers, etc.

lib/Terminal/Widgets/Simple/README.md

@@ -0,0 +1,12 @@
+# Simple API Modules
+
+Modules here are primarily intended to provide simpler interfaces to existing
+functionality, often by providing helper functions or opinionated wrappers that
+make the most commonly expected choices.
+
+For example, the simplified TopLevel and App classes that allow the `examples/`
+scripts to mostly ignore those details are here.
+
+If your module/class would be generally useful to any program wanting a simple
+API, you should also import/export it in the `Terminal::Widgets::Simple` module
+so that callers don't need to import all of the `Simple` modules individually.

lib/Terminal/Widgets/Utils/README.md

@@ -0,0 +1,5 @@
+# Utility Modules
+
+This directory contains modules that are primarily intended as collections of
+utility functions for widgets or other modules.  For example, color space
+calculations and data format conversions would belong here.

lib/Terminal/Widgets/Viewer/README.md

@@ -0,0 +1,23 @@
+# Viewer Widgets
+
+This directory contains widgets that are primarily viewers for data, but which
+are NOT charts/visualizers (use the `Viz/` directory for that).
+
+For example, log tailers, tree navigators, and doc viewers all belong here.
+
+
+## Interactivity
+
+Viewers can have basic viewing interactivity, such as scroll or expand/collapse
+actions, but are not primarily intended as inputs.  Widgets that primarily
+act as inputs should prefer the `Input/` directory instead.
+
+For example, a rich text _viewer_ would belong here, but a rich text _editor_
+would belong in `Input/`.
+
+
+## Efficiency
+
+Like the visualizers, viewers can often operate on large data sets.  Care
+should be taken to work as efficiently/lazily as possible on large or complex
+files, large directory trees, and so forth.

lib/Terminal/Widgets/Viz/README.md

@@ -0,0 +1,24 @@
+# Data Visualizer Widgets
+
+This directory contains widgets that are primarily data visualizers, such as
+charting widgets.
+
+
+## Interactivity
+
+Some of these visualizers will be non-interactive, but it is perfectly
+reasonable to have basic viewing interactivity, such as pan and zoom actions.
+They are _not_ intended to be used as inputs, so if your widget allows you to
+_edit_ the data being visualized, it probably belongs in `Input/` instead.
+
+
+## Efficiency
+
+Widgets here should be designed so that they are not constantly updating their
+full area if possible.  For example, the SmokeChart widget keeps track of a
+"sweep line" where updates occur, moving the sweep line as needed and leaving
+other columns/rows unchanged.  This is vastly more efficient than the common
+live charting style that updates in a fixed location (at one edge usually) and
+moves the entire chart each time new data arrives.  As a pleasant side effect,
+this also makes an actively updating SmokeChart much more "visually quiet",
+and thus less distracting for the user.

lib/Terminal/Widgets/Volatile/README.md

@@ -0,0 +1,6 @@
+# Volatile Data Structures
+
+This directory contains classes that represent volatile data, such as directory
+trees, network neighborhoods, log files, etc.  In effect these are "caches for
+outside reality", so that widgets that want to display this kind of information
+don't need to manage the finicky details themselves.