@xeplr/ui-utils 1.0.0 → 1.0.2

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;
+}

package/src/textField/useTextFieldController.js

@@ -0,0 +1,101 @@
+import { useState, useMemo, useCallback } from 'react';
+import { toValue, normalise, validate, remaining, TEXT_TYPES } from './textField.js';
+
+/**
+ * @param {object} props
+ * @param {'text'|'multiline'|'search'} [props.type='text']
+ * @param {string} [props.value]          — controlled
+ * @param {string} [props.defaultValue]   — uncontrolled initial
+ * @param {(value) => void} [props.onChange]
+ * @param {(value) => void} [props.onCommit]  — on blur/Enter, after normalising
+ * @param {boolean} [props.required]
+ * @param {number} [props.minLength]
+ * @param {number} [props.maxLength]
+ * @param {RegExp|string} [props.pattern]
+ * @param {boolean} [props.trim]          — normalise away surrounding space
+ * @param {string} [props.placeholder]
+ * @param {boolean} [props.disabled]
+ * @param {number} [props.rows]           — multiline only
+ */
+export function useTextFieldController(props) {
+  props = props || {};
+  var type = props.type || 'text';
+  if (TEXT_TYPES.indexOf(type) === -1) {
+    throw new Error('[xeplr-ui-utils:TextField] Unknown type: ' + type + '. Expected one of ' + TEXT_TYPES.join(', '));
+  }
+
+  var controlled = props.value !== undefined;
+  var [inner, setInner] = useState(toValue(props.defaultValue));
+  var raw = controlled ? toValue(props.value) : inner;
+
+  // Errors appear on COMMIT, not on every keystroke. A required field that
+  // says "This is required" while you are still typing the first letter is
+  // shouting at somebody for not having finished.
+  var [touched, setTouched] = useState(false);
+
+  var options = useMemo(function() {
+    return {
+      required: props.required,
+      requiredMessage: props.requiredMessage,
+      minLength: props.minLength,
+      maxLength: props.maxLength,
+      pattern: props.pattern,
+      patternMessage: props.patternMessage,
+      trim: props.trim
+    };
+  }, [props.required, props.requiredMessage, props.minLength, props.maxLength,
+      props.pattern, props.patternMessage, props.trim]);
+
+  var handleChange = useCallback(function(e) {
+    var next = e && e.target ? e.target.value : e;
+    // Capped as you type, because a maxLength you can exceed and are told off
+    // for afterwards is a maxLength that does nothing.
+    if (props.maxLength != null) next = String(next).slice(0, props.maxLength);
+    if (!controlled) setInner(next);
+    if (props.onChange) props.onChange(next);
+  }, [controlled, props.maxLength, props.onChange]);
+
+  var commit = useCallback(function(value) {
+    var next = normalise(value, options);
+    setTouched(true);
+    if (!controlled && next !== value) setInner(next);
+    if (props.onCommit) props.onCommit(next);
+    else if (next !== value && props.onChange) props.onChange(next);
+  }, [controlled, options, props.onChange, props.onCommit]);
+
+  var handleBlur = useCallback(function(e) {
+    commit(e && e.target ? e.target.value : raw);
+  }, [commit, raw]);
+
+  var handleKeyDown = useCallback(function(e) {
+    // Enter commits a single-line field; in a multiline one it is a newline.
+    if (e.key === 'Enter' && type !== 'multiline') commit(e.target.value);
+    if (e.key === 'Escape' && props.onCancel) props.onCancel();
+  }, [commit, type, props.onCancel]);
+
+  var handleClear = useCallback(function() {
+    if (!controlled) setInner('');
+    if (props.onChange) props.onChange('');
+    if (props.onCommit) props.onCommit('');
+  }, [controlled, props.onChange, props.onCommit]);
+
+  var error = touched ? validate(raw, options) : null;
+
+  return {
+    type: type,
+    raw: raw,
+    error: error,
+    remaining: remaining(raw, props.maxLength),
+    placeholder: props.placeholder,
+    disabled: props.disabled,
+    required: props.required,
+    maxLength: props.maxLength,
+    rows: props.rows,
+    label: props.label,
+    help: props.help,
+    handleChange: handleChange,
+    handleBlur: handleBlur,
+    handleKeyDown: handleKeyDown,
+    handleClear: handleClear
+  };
+}

package/src/textField/validateDesign.js

@@ -0,0 +1,3 @@
+export var TEXT_FIELD_RULES = [
+  { selector: 'input[type="text"], input[type="search"], textarea, .xeplr-textfield-input', label: 'Text input element' }
+];