@xeplr/ui-utils 1.0.1 → 1.0.2

package/src/progress/designs/progressNotifier.css

@@ -0,0 +1,73 @@
+/* Progress notifier. Namespaced xpn-* so it cannot collide with a host app's
+   own rules, and self-contained so mounting it never depends on the host
+   having loaded some other stylesheet first.
+
+   var(--xeplr-*, fallback) throughout — picks up @xeplr/ui-account's theme
+   tokens when that stylesheet is present, and looks right without it. */
+
+.xpn {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  /* Zero height when it renders nothing: the component returns null while
+     idle, and this keeps the visible state from adding margin a host did not
+     ask for. */
+  margin: 0;
+}
+
+.xpn-text {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.35;
+  color: var(--xeplr-muted, #6b7280);
+  /* A driver's error is one long line with no spaces in it more often than
+     not, and must not stretch whatever it is sitting in. */
+  overflow-wrap: anywhere;
+}
+
+.xpn--error .xpn-text { color: var(--xeplr-danger, #c2372e); }
+.xpn--complete .xpn-text { color: var(--xeplr-success, #059669); }
+
+/* ── the bar ─────────────────────────────────────────────────────────────
+
+   INDETERMINATE, always. Nothing this reports on can honestly say how far
+   through it is — a GROUP BY over twenty million rows knows only that it is
+   running — so the movement says "alive" and the text beside it carries what
+   is actually true. A bar creeping toward 60% would be an invented number. */
+
+.xpn-bar {
+  position: relative;
+  width: 100%;
+  height: 3px;
+  border-radius: 2px;
+  overflow: hidden;
+  background: color-mix(in srgb, var(--xeplr-accent, #2563eb) 18%, transparent);
+}
+
+.xpn-bar span {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: block;
+  width: 40%;
+  height: 100%;
+  border-radius: 2px;
+  background: var(--xeplr-accent, #2563eb);
+  animation: xpn-slide 1.1s ease-in-out infinite;
+}
+
+@keyframes xpn-slide {
+  0%   { transform: translateX(-100%); }
+  100% { transform: translateX(250%); }
+}
+
+/* Motion is the only thing carrying "still going" here, so it is not simply
+   removed — it is replaced with a filled, dimmed bar that still reads as a
+   state rather than as a finished one. */
+@media (prefers-reduced-motion: reduce) {
+  .xpn-bar span {
+    animation: none;
+    width: 100%;
+    opacity: 0.55;
+  }
+}

package/src/progress/progressSource.js

@@ -0,0 +1,168 @@
+// PROGRESS NOTIFIER — the model.
+//
+// Long-running work on the server must never be silent on the client. Not a
+// spinner that means "something, somewhere" — the actual thing it is doing,
+// updated as it does it, until it says it is finished.
+//
+// ── WHY THIS PACKAGE AND NOT EACH APP ────────────────────────────────────
+//
+// Because it kept being rebuilt. A report had one, a dashboard widget had one,
+// and the next screen that needed one wrote a third with its own bar, its own
+// keyframes and its own idea of what "running" looks like. They drift, and the
+// drift is visible: the same operation reports differently depending on which
+// screen you started it from.
+//
+// ── THE EVENT SHAPE, AND WHY IT IS NOT THE APP'S ─────────────────────────
+//
+// This module knows nothing about SSE, tickets, topics or run stores. An app
+// attaches its own stream once, adapting whatever it publishes into:
+//
+//     { key, continue: true|false, status?, data }
+//
+//   key      — what the work is ABOUT, chosen by the back end: a cube id, a
+//              move run id, a report id. A notifier is mounted with the same
+//              key, so a screen listens using an id it already has rather than
+//              one it has to be handed back.
+//   continue — TRUE while the work is still going. This is the whole of the
+//              visibility rule: a notifier shows itself when it hears `true`
+//              for its key and is otherwise invisible. Nothing on the client
+//              decides when to appear.
+//   status   — optional, and only interesting for how it ENDED: 'error' when
+//              it failed. Absent means the ordinary case.
+//   data     — whatever the work knows about itself. Free-form, deliberately:
+//              the server sends what it has, and the SENTENCE is made here. A
+//              server that formats prose cannot be re-worded without a
+//              deployment, and cannot be translated at all.
+//
+// ── HIDDEN UNTIL TOLD OTHERWISE ──────────────────────────────────────────
+//
+// A notifier renders nothing until an event for its key arrives. That is what
+// makes it safe to put on ten components: they all sit at zero height, and the
+// one whose work is running — or all of them, if they share a key — appear
+// together. Nothing needs to know which screen started the job, and a screen
+// opened halfway through a build shows it without asking anybody.
+
+var _subscribe = null;
+
+/**
+ * Point the notifier at this app's event stream. Called ONCE at startup.
+ *
+ * `subscribe(handler)` must call `handler({ key, status, data })` for every
+ * event and return an unsubscribe function.
+ *
+ * Nothing here opens a connection: an app already has one stream and should
+ * not grow a second for this. The adapter is where its own event shape is
+ * translated — see the notes on the contract above.
+ */
+export function attachProgressSource(subscribe) {
+  _subscribe = typeof subscribe === 'function' ? subscribe : null;
+}
+
+/** Whether an app has attached a stream. False means every notifier is inert. */
+export function progressSourceAttached() {
+  return Boolean(_subscribe);
+}
+
+/**
+ * Listen for events about one key.
+ *
+ * Returns an unsubscribe function, always — including when no source is
+ * attached, so a component's cleanup never has to check. A notifier mounted in
+ * an app that never attached one simply shows nothing, rather than throwing in
+ * a render.
+ */
+export function subscribeToProgress(key, handler) {
+  if (!_subscribe || !key) return function() {};
+  return _subscribe(function(evt) {
+    if (!evt || evt.key !== key) return;
+    handler(normalize(evt));
+  }) || function() {};
+}
+
+/**
+ * One shape for the component, whichever way the app phrased it.
+ *
+ * `continue` is the field the back end sends and the one the contract is
+ * written around, but it cannot be a variable name in JavaScript — so it is
+ * turned into a plain state here, once, rather than being read as
+ * `evt['continue']` at four call sites.
+ *
+ * An event with neither `continue` nor a status is treated as STILL RUNNING.
+ * Being wrong that way leaves a bar spinning until the next event; being wrong
+ * the other way hides a job that is still going, which is the failure this
+ * whole component exists to prevent.
+ */
+function normalize(evt) {
+  var state = 'running';
+  if (evt.status === 'error') state = 'error';
+  else if (evt.continue === false) state = 'complete';
+  else if (evt.status === 'complete') state = 'complete';
+
+  return { key: evt.key, state: state, data: evt.data || {} };
+}
+
+// ── turning `data` into a sentence ───────────────────────────────────────
+
+/** Thousands separators, because 5022241 is not a number anybody reads. */
+function count(n) {
+  return Number(n).toLocaleString();
+}
+
+/**
+ * What to SAY about a piece of work, from whatever it reported.
+ *
+ * The order is deliberate. An explicit `message` wins, because work that knows
+ * its own phase ("Rolling the rows up…") says it better than anything derived.
+ * Failing that, the counters are assembled — and counters are the honest thing
+ * to show, since almost nothing here can report a percentage: a GROUP BY does
+ * not know how far through it is, and a bar claiming 60% would be invented.
+ *
+ * The last resort is a plain sentence rather than an empty string. "Working…"
+ * next to a moving bar is a true statement; a blank line beside it looks like
+ * the thing has stalled.
+ *
+ * A SAMPLE, in the sense that these are the fields our work happens to send
+ * today. Adding one is a line here, not a change to any server.
+ */
+export function describeProgress(data, noun) {
+  var d = data || {};
+  if (d.message) return d.message;
+
+  var parts = [];
+  // Read vs loaded, kept separate: a move that read 50,000 rows and wrote none
+  // is the failure most worth seeing, and one merged number hides it.
+  if (d.rowsRead != null) parts.push(count(d.rowsRead) + ' rows read');
+  if (d.rowsLoaded != null) parts.push(count(d.rowsLoaded) + ' loaded');
+  if (d.rowsScanned != null) parts.push(count(d.rowsScanned) + ' rows scanned');
+  if (d.groupCount != null) parts.push(count(d.groupCount) + ' groups');
+  if (d.batches != null) parts.push(count(d.batches) + ' batches');
+  if (d.cubeRows != null) parts.push(count(d.cubeRows) + ' rows');
+
+  if (parts.length) return parts.join(' · ') + '…';
+  return 'Working on the ' + (noun || 'task') + '…';
+}
+
+/**
+ * What to say once it has finished — the part people actually wait for.
+ *
+ * Separate from the running text because the tense and the content differ: a
+ * finished job reports a RESULT and how long it took, not what it was doing.
+ */
+export function describeComplete(data, noun) {
+  var d = data || {};
+  if (d.message) return d.message;
+
+  var what = null;
+  if (d.cubeRows != null) what = count(d.cubeRows) + ' rows';
+  else if (d.rowsLoaded != null) what = count(d.rowsLoaded) + ' rows';
+  else if (d.groupCount != null) what = count(d.groupCount) + ' groups';
+
+  var took = d.durationMs != null
+    ? ' in ' + (d.durationMs < 1000
+        ? d.durationMs + 'ms'
+        : (d.durationMs / 1000).toFixed(1) + 's')
+    : '';
+
+  if (what) return 'Finished — ' + what + took;
+  return 'Finished' + (took || '') + (noun ? ' — ' + noun : '');
+}

package/src/rangeField/designs/RangeFieldSample.jsx

@@ -0,0 +1,25 @@
+import DateFieldSample from '../../dateField/designs/DateFieldSample.jsx';
+import './rangeField.css';
+
+/**
+ * RangeField — design. From and To rendered as ONE field, side by side,
+ * sharing a row — not two independent fields that happen to sit near each
+ * other. That's the actual point of this component: a caller reaching for
+ * "start" and "end" as two separate labeled boxes gets visual distance
+ * between two things that are really one idea; this gives them the one idea.
+ */
+export default function RangeFieldSample({ fromLabel, toLabel, from, to }) {
+  return (
+    <div className="xeplr-rangefield">
+      <div className="xeplr-rangefield-field">
+        <span className="xeplr-rangefield-label">{fromLabel}</span>
+        <DateFieldSample {...from} />
+      </div>
+      <span className="xeplr-rangefield-sep" aria-hidden="true">→</span>
+      <div className="xeplr-rangefield-field">
+        <span className="xeplr-rangefield-label">{toLabel}</span>
+        <DateFieldSample {...to} />
+      </div>
+    </div>
+  );
+}

package/src/rangeField/designs/index.js

@@ -0,0 +1 @@
+export { default as RangeFieldSample } from './RangeFieldSample.jsx';

package/src/rangeField/designs/rangeField.css

@@ -0,0 +1,26 @@
+/* Namespaced xeplr-rangefield-* so a host's own styles can't collide with it. */
+.xeplr-rangefield {
+  display: flex;
+  align-items: flex-end;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.xeplr-rangefield-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex: 1;
+  min-width: 160px;
+}
+.xeplr-rangefield-label {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--xeplr-muted, #6b7280);
+}
+/* Purely a visual hint that these two boxes are one idea, not a real
+   separator — hidden from assistive tech via aria-hidden in the design. */
+.xeplr-rangefield-sep {
+  padding-bottom: 10px;
+  color: var(--xeplr-muted-2, #9aa1ad);
+  font-size: 13px;
+}

package/src/rangeField/pages.jsx

@@ -0,0 +1,10 @@
+import { useRangeFieldController } from './useRangeFieldController.js';
+import RangeFieldSample from './designs/RangeFieldSample.jsx';
+import { useDesignValidator } from '../fileUpload/validateDesign.js';
+import { RANGE_FIELD_RULES } from './validateDesign.js';
+
+export function RangeFieldPage(props) {
+  var controller = useRangeFieldController(props);
+  var ref = useDesignValidator('RangeFieldPage', RANGE_FIELD_RULES);
+  return <div ref={ref}><RangeFieldSample {...controller} /></div>;
+}

package/src/rangeField/rangeField.js

@@ -0,0 +1,29 @@
+/**
+ * RangeField — pure model. No React.
+ *
+ * NOT DateRange (see ../dateRange) — that's a full quick-preset/range/single
+ * POPOVER picker, built for a report filter that also needs to remember "the
+ * last 30 days" as a living selection. This is just the two-input pair
+ * itself: a From and a To, rendered as one field, for a caller that already
+ * knows it wants an explicit range and has nowhere to put a popover (a
+ * wizard step, a form section) — DateRange's own Range tab is exactly this
+ * shape internally and could sit on top of this instead of duplicating it.
+ *
+ * Two flavours, mirroring dateField's (minus 'age' — a range of ages isn't
+ * a thing):
+ *   - 'date'     → ISO date strings (YYYY-MM-DD)
+ *   - 'datetime' → ISO datetime strings (YYYY-MM-DDTHH:mm)
+ */
+export var RANGE_TYPES = ['date', 'datetime'];
+
+export function emptyRange() {
+  return { from: '', to: '' };
+}
+
+export function normalizeRange(range) {
+  return { from: (range && range.from) || '', to: (range && range.to) || '' };
+}
+
+export function rangeIsSet(range) {
+  return Boolean(range && (range.from || range.to));
+}

package/src/rangeField/useRangeFieldController.js

@@ -0,0 +1,52 @@
+import { useDateFieldController } from '../dateField/useDateFieldController.js';
+import { normalizeRange } from './rangeField.js';
+
+/**
+ * Two DateField controllers, cross-bounded — From can't be set past To, To
+ * can't be set before From, each side gets that for free rather than the
+ * caller re-deriving it. Composition over reimplementation: this is not a
+ * second date-input implementation, it's dateField's, called twice.
+ *
+ * @param {object} props
+ * @param {'date'|'datetime'} [props.type='date']
+ * @param {{from, to}} [props.value] — controlled; {from:'', to:''} if absent
+ * @param {(value: {from, to}) => void} [props.onChange]
+ * @param {Date|string} [props.min] — floor for From (and, absent an explicit To, for To too)
+ * @param {Date|string} [props.max] — ceiling for To (and, absent an explicit From, for From too)
+ * @param {boolean} [props.disabled]
+ * @param {string} [props.fromLabel='From']
+ * @param {string} [props.toLabel='To']
+ * @param {string} [props.toPlaceholder] — e.g. "Now", for an open-ended end
+ */
+export function useRangeFieldController(props) {
+  props = props || {};
+  var type = props.type || 'date';
+  var range = normalizeRange(props.value);
+
+  var from = useDateFieldController({
+    type: type,
+    value: range.from || null,
+    onChange: function(v) { if (props.onChange) props.onChange({ from: v || '', to: range.to }); },
+    min: props.min,
+    max: range.to || props.max,
+    disabled: props.disabled,
+    placeholder: props.fromPlaceholder
+  });
+
+  var to = useDateFieldController({
+    type: type,
+    value: range.to || null,
+    onChange: function(v) { if (props.onChange) props.onChange({ from: range.from, to: v || '' }); },
+    min: range.from || props.min,
+    max: props.max,
+    disabled: props.disabled,
+    placeholder: props.toPlaceholder
+  });
+
+  return {
+    fromLabel: props.fromLabel || 'From',
+    toLabel: props.toLabel || 'To',
+    from: from,
+    to: to
+  };
+}

package/src/rangeField/validateDesign.js

@@ -0,0 +1,3 @@
+export var RANGE_FIELD_RULES = [
+  { selector: '.xeplr-rangefield-field', label: 'Range field wrapper (from/to)' }
+];

package/src/textField/designs/TextFieldSample.jsx

@@ -0,0 +1,75 @@
+import './textField.css';
+
+// The default LOOK. Presentation only — every value it renders comes in as a
+// prop, so an app that wants a different one supplies its own design and this
+// is never loaded.
+//
+// Nothing here is hard-coded to a colour or an edge: the CSS reads
+// --xeplr-input-* custom properties, so "bottom rule only" is a theme setting
+// rather than a fork of this file.
+export default function TextFieldSample({
+  type, raw, error, remaining, placeholder, disabled, required, maxLength, rows,
+  label, help, handleChange, handleBlur, handleKeyDown, handleClear
+}) {
+  var multiline = type === 'multiline';
+  var search = type === 'search';
+
+  return (
+    <div className={'xeplr-textfield' + (error ? ' xeplr-textfield-invalid' : '')}>
+      {label && (
+        <label className="xeplr-textfield-label">
+          {label}{required && <span className="xeplr-textfield-required" aria-hidden="true"> *</span>}
+        </label>
+      )}
+
+      <div className="xeplr-textfield-control">
+        {multiline ? (
+          <textarea
+            className="xeplr-textfield-input"
+            value={raw}
+            rows={rows || 4}
+            placeholder={placeholder}
+            disabled={disabled}
+            maxLength={maxLength}
+            aria-invalid={error ? 'true' : undefined}
+            onChange={handleChange}
+            onBlur={handleBlur}
+          />
+        ) : (
+          <input
+            className="xeplr-textfield-input"
+            type={search ? 'search' : 'text'}
+            value={raw}
+            placeholder={placeholder}
+            disabled={disabled}
+            maxLength={maxLength}
+            aria-invalid={error ? 'true' : undefined}
+            onChange={handleChange}
+            onBlur={handleBlur}
+            onKeyDown={handleKeyDown}
+          />
+        )}
+
+        {/* Only when there is something to clear — a permanently visible ✕ on
+            an empty box is a control that does nothing most of the time. */}
+        {search && raw && !disabled && (
+          <button type="button" className="xeplr-textfield-clear" onClick={handleClear} title="Clear">✕</button>
+        )}
+      </div>
+
+      {/* The error REPLACES the help text rather than stacking under it: two
+          lines of guidance where one contradicts the other is worse than one. */}
+      {error ? (
+        <p className="xeplr-textfield-error">{error}</p>
+      ) : help ? (
+        <p className="xeplr-textfield-help">{help}</p>
+      ) : null}
+
+      {/* Shown near the limit, not always. A counter reading 486 of 500 from
+          the moment the field appears is noise. */}
+      {remaining != null && maxLength != null && remaining <= Math.max(10, maxLength * 0.1) && (
+        <p className="xeplr-textfield-count">{remaining} left</p>
+      )}
+    </div>
+  );
+}

package/src/textField/designs/index.js

@@ -0,0 +1 @@
+export { default as TextFieldSample } from './TextFieldSample.jsx';

package/src/textField/designs/textField.css

@@ -0,0 +1,92 @@
+/* Every value here comes from a --xeplr-input-* custom property, with the
+   shipped default as its fallback. That is what makes "border: bottom only"
+   a theme setting rather than a fork of this stylesheet — see the `input`
+   section of default.theme.json and inputStyleVars(). */
+
+/* The gap is the control's OWN spacing when it stands alone in a form. Inside
+   a grid the row owns the spacing, so a host can zero it — see .dsh-prop. */
+.xeplr-textfield { display: block; margin-bottom: var(--xeplr-input-text-gap, 12px); }
+
+/* The label takes the FULL Font block, so anything the theme accepts for it
+   actually renders — underline included. A property the theme takes and the
+   stylesheet ignores is a setting that silently does nothing. */
+.xeplr-textfield-label {
+  display: block;
+  font-family: var(--xeplr-input-text-label-family, inherit);
+  font-size: var(--xeplr-input-text-label-size, 11px);
+  font-weight: var(--xeplr-input-text-label-weight, 600);
+  font-style: var(--xeplr-input-text-label-style, normal);
+  font-variant: var(--xeplr-input-text-label-variant, normal);
+  color: var(--xeplr-input-text-label-color, #6b6a63);
+  line-height: var(--xeplr-input-text-label-line-height, 1.3);
+  letter-spacing: var(--xeplr-input-text-label-spacing, .03em);
+  text-align: var(--xeplr-input-text-label-align, left);
+  text-transform: var(--xeplr-input-text-label-transform, uppercase);
+  text-decoration: var(--xeplr-input-text-label-decoration, none);
+  opacity: var(--xeplr-input-text-label-opacity, 1);
+  margin-bottom: 5px;
+}
+.xeplr-textfield-required { color: var(--xeplr-input-text-invalid-color, #c2372e); }
+
+.xeplr-textfield-control { position: relative; display: flex; }
+
+.xeplr-textfield-input {
+  width: 100%;
+  font: inherit;
+  font-size: var(--xeplr-input-text-font-size, 12.5px);
+  color: var(--xeplr-input-text-color, #1a1a19);
+  background: var(--xeplr-input-text-bg, #fff);
+  padding: var(--xeplr-input-text-padding, 7px 9px);
+  /* Each edge on its own, so a theme can keep one and drop three. */
+  border-style: var(--xeplr-input-text-border-style, solid);
+  border-color: var(--xeplr-input-text-border-color, #e2e1d9);
+  border-top-width: var(--xeplr-input-text-border-top, 1px);
+  border-right-width: var(--xeplr-input-text-border-right, 1px);
+  border-bottom-width: var(--xeplr-input-text-border-bottom, 1px);
+  border-left-width: var(--xeplr-input-text-border-left, 1px);
+  border-radius: var(--xeplr-input-text-radius, 6px);
+  transition: border-color .12s ease, box-shadow .12s ease;
+}
+.xeplr-textfield-input:hover:not(:disabled) {
+  border-color: var(--xeplr-input-text-border-hover, #b6b4a8);
+}
+.xeplr-textfield-input:focus {
+  outline: none;
+  border-color: var(--xeplr-input-text-border-focus, #2563eb);
+  box-shadow: 0 0 0 var(--xeplr-input-text-ring, 3px) var(--xeplr-input-text-ring-color, rgba(37, 99, 235, .15));
+}
+.xeplr-textfield-input:disabled { opacity: .55; cursor: not-allowed; }
+.xeplr-textfield-input::placeholder { color: var(--xeplr-input-text-placeholder, #9d9b92); }
+
+textarea.xeplr-textfield-input { resize: vertical; min-height: 64px; }
+
+.xeplr-textfield-invalid .xeplr-textfield-input {
+  border-color: var(--xeplr-input-text-invalid-color, #c2372e);
+}
+.xeplr-textfield-invalid .xeplr-textfield-input:focus {
+  box-shadow: 0 0 0 var(--xeplr-input-text-ring, 3px) var(--xeplr-input-text-invalid-ring, rgba(194, 55, 46, .15));
+}
+
+.xeplr-textfield-clear {
+  position: absolute; right: 6px; top: 50%; transform: translateY(-50%);
+  border: none; background: none; cursor: pointer;
+  color: var(--xeplr-input-text-label-color, #6b6a63);
+  font-size: 11px; padding: 2px 4px; border-radius: 4px;
+}
+.xeplr-textfield-clear:hover { background: rgba(0, 0, 0, .06); }
+
+.xeplr-textfield-help,
+.xeplr-textfield-error,
+.xeplr-textfield-count {
+  margin: 5px 0 0;
+  font-size: var(--xeplr-input-text-help-size, 11px);
+  line-height: 1.5;
+}
+.xeplr-textfield-help {
+  font-family: var(--xeplr-input-text-help-family, inherit);
+  font-style: var(--xeplr-input-text-help-style, normal);
+  text-decoration: var(--xeplr-input-text-help-decoration, none);
+  color: var(--xeplr-input-text-help-color, #6b6a63);
+}
+.xeplr-textfield-error { color: var(--xeplr-input-text-invalid-color, #c2372e); }
+.xeplr-textfield-count { color: var(--xeplr-input-text-label-color, #6b6a63); text-align: right; }

package/src/textField/pages.jsx

@@ -0,0 +1,10 @@
+import { useTextFieldController } from './useTextFieldController.js';
+import TextFieldSample from './designs/TextFieldSample.jsx';
+import { useDesignValidator } from '../fileUpload/validateDesign.js';
+import { TEXT_FIELD_RULES } from './validateDesign.js';
+
+export function TextFieldPage(props) {
+  var controller = useTextFieldController(props);
+  var ref = useDesignValidator('TextFieldPage', TEXT_FIELD_RULES);
+  return <div ref={ref}><TextFieldSample {...controller} /></div>;
+}

package/src/textField/textField.js

@@ -0,0 +1,65 @@
+/**
+ * TextField — pure model. No React.
+ *
+ * The plain text input, and the two shapes that are the same control with a
+ * different edge: a multi-line one and a search one. Kept together because
+ * they are one thing to style — an app that wants a bottom-rule-only textbox
+ * wants a bottom-rule-only search box too, and splitting them is how those
+ * drift apart.
+ */
+
+export var TEXT_TYPES = ['text', 'multiline', 'search'];
+
+/**
+ * What the control accepts as a value. Anything nullish is the empty string:
+ * a controlled input handed `undefined` switches to uncontrolled mid-life and
+ * React warns about it, which is a bug that only appears once somebody clears
+ * a field.
+ */
+export function toValue(raw) {
+  return raw === null || raw === undefined ? '' : String(raw);
+}
+
+/**
+ * Trimming is a CHOICE, not a default. " " is a legitimate value in a search
+ * box and a mistake in a name field, and only the caller knows which.
+ */
+export function normalise(raw, options) {
+  var value = toValue(raw);
+  var opts = options || {};
+  if (opts.trim) value = value.trim();
+  if (opts.maxLength != null && value.length > opts.maxLength) value = value.slice(0, opts.maxLength);
+  return value;
+}
+
+/**
+ * Whether the value satisfies the constraints, and what to say if not.
+ *
+ * Returns null when it is fine — so a caller can write `error = validate(...)`
+ * and render it directly, rather than unpacking a result object to find out
+ * there was nothing wrong.
+ */
+export function validate(raw, options) {
+  var opts = options || {};
+  var value = toValue(raw);
+  var trimmed = value.trim();
+
+  if (opts.required && !trimmed) return opts.requiredMessage || 'This is required';
+  if (opts.minLength != null && trimmed.length > 0 && trimmed.length < opts.minLength) {
+    return 'At least ' + opts.minLength + ' characters';
+  }
+  if (opts.maxLength != null && value.length > opts.maxLength) {
+    return 'At most ' + opts.maxLength + ' characters';
+  }
+  if (opts.pattern) {
+    var re = opts.pattern instanceof RegExp ? opts.pattern : new RegExp(opts.pattern);
+    if (trimmed && !re.test(trimmed)) return opts.patternMessage || 'That is not a valid value';
+  }
+  return null;
+}
+
+/** How many characters are left, or null when there is no limit to count to. */
+export function remaining(raw, maxLength) {
+  if (maxLength == null) return null;
+  return maxLength - toValue(raw).length;
+}