@xeplr/ui-utils 1.0.0 → 1.0.2

package/src/dateRange/designs/DateRangeSample.jsx

@@ -0,0 +1,138 @@
+import './dateRange.css';
+
+var TABS = [
+  ['quick', 'Quick date'],
+  ['range', 'Range'],
+  ['single', 'Single']
+];
+
+/**
+ * DateRange — design. Presentation only: everything arrives as props from
+ * useDateRangeController, so an app can swap this out without touching the
+ * behaviour.
+ *
+ * Three ways in, because they are genuinely different questions:
+ *   Quick   — "the current month", which stays current as time passes
+ *   Range   — two explicit dates
+ *   Single  — one date, month or year, typed
+ */
+export default function DateRangeSample(props) {
+  return (
+    <div className="xeplr-daterange">
+      <div className="xeplr-daterange-tabs">
+        {TABS.map(function(t) {
+          return (
+            <button
+              key={t[0]}
+              type="button"
+              data-xeplr-daterange-tab={t[0]}
+              className={props.tab === t[0] ? 'active' : ''}
+              onClick={function() { props.setTab(t[0]); }}
+            >
+              {t[1]}
+            </button>
+          );
+        })}
+      </div>
+
+      {props.tab === 'quick' && (
+        <div className="xeplr-daterange-list">
+          {props.presets.map(function(p) {
+            var on = props.value && props.value.kind === 'quick' && props.value.preset === p.key;
+            return (
+              <button
+                key={p.key}
+                type="button"
+                data-xeplr-daterange-preset={p.key}
+                className={'xeplr-daterange-item' + (on ? ' on' : '')}
+                onClick={function() { props.selectPreset(p.key); }}
+              >
+                {p.label}
+              </button>
+            );
+          })}
+        </div>
+      )}
+
+      {props.tab === 'range' && (
+        <div className="xeplr-daterange-body">
+          <label className="xeplr-daterange-field">
+            <span>From</span>
+            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }} />
+          </label>
+          <label className="xeplr-daterange-field">
+            <span>To</span>
+            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }} />
+          </label>
+          {/* One-sided is legitimate — "everything since April" is a real
+              answer — so it is stated rather than blocked. */}
+          <div className="xeplr-daterange-note">Leave either side empty for an open-ended range.</div>
+        </div>
+      )}
+
+      {props.tab === 'single' && (
+        <div className="xeplr-daterange-body">
+          <input
+            className="xeplr-daterange-input"
+            value={props.single}
+            placeholder="1/1/2022, May 2022, or 2022"
+            onChange={function(e) { props.setSingle(e.target.value); }}
+            onBlur={function() { props.commitSingle(false); }}
+            onKeyDown={function(e) {
+              if (e.key !== 'Enter') return;
+              e.preventDefault();
+              props.commitSingle(true);
+            }}
+          />
+          {/* WHAT YOU PROBABLY MEAN, one click away. "j" is three months and
+              every month is several years — the list is shorter than typing
+              the rest, and it is ordered so the year already on screen comes
+              first. Months and years only; a day is quicker to finish typing
+              than to find among thirty. */}
+          {props.suggestions && props.suggestions.length > 0 && (
+            <ul className="xeplr-daterange-suggest">
+              {props.suggestions.map(function(s) {
+                return (
+                  <li key={s.value}>
+                    <button
+                      type="button"
+                      // MOUSEDOWN, not click: the input's onBlur commits what
+                      // is typed and would close this list before a click ever
+                      // landed on it.
+                      onMouseDown={function(e) { e.preventDefault(); props.applySuggestion(s.value); }}
+                    >
+                      <span>{s.label}</span>
+                      {s.note && <span className="xeplr-daterange-suggest-note">{s.note}</span>}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+
+          {/* A month or a year IS a range, and showing the resolved span is the
+              quickest way to confirm "May 2022" was read as intended. */}
+          <div className="xeplr-daterange-note">
+            {props.single
+              ? (props.singleParsed ? props.singleParsed.from + ' → ' + props.singleParsed.to : 'Not a date yet')
+              : 'A day, a whole month, or a whole year.'}
+          </div>
+        </div>
+      )}
+
+      <div className="xeplr-daterange-foot">
+        {/* Absent, not disabled, where the host cannot accept an empty
+            selection — a control you can press that does nothing is worse
+            than one that was never offered. */}
+        {props.allowClear && (
+          <button type="button" className="xeplr-daterange-clear" onClick={props.clear}>Clear</button>
+        )}
+        {props.label && <span className="xeplr-daterange-current">{props.label}</span>}
+      </div>
+
+      {props.inheritedLabel && !props.value && (
+        <div className="xeplr-daterange-inherited">Using {props.inheritedLabel}</div>
+      )}
+    </div>
+  );
+}

package/src/dateRange/designs/dateRange.css

@@ -0,0 +1,69 @@
+/* Namespaced xeplr-daterange-* so a host's own styles can't collide with it. */
+.xeplr-daterange {
+  display: flex;
+  flex-direction: column;
+  width: 260px;
+  background: var(--xeplr-surface, #fff);
+  border: 1px solid var(--xeplr-border-strong, #c9cdd6);
+  border-radius: 9px;
+  overflow: hidden;
+  color: inherit;
+}
+.xeplr-daterange-tabs { display: flex; border-bottom: 1px solid var(--xeplr-border, #e2e5eb); }
+.xeplr-daterange-tabs button {
+  flex: 1; padding: 7px 4px; border: none; background: none; cursor: pointer;
+  font-size: 11.5px; font-weight: 600; color: var(--xeplr-muted, #6b7280);
+  border-bottom: 2px solid transparent;
+}
+.xeplr-daterange-tabs button.active {
+  color: var(--xeplr-accent, #4f5fd6);
+  border-bottom-color: var(--xeplr-accent, #4f5fd6);
+}
+.xeplr-daterange-list { max-height: 240px; overflow-y: auto; padding: 4px; }
+.xeplr-daterange-item {
+  display: block; width: 100%; text-align: left;
+  padding: 5px 7px; border: none; border-radius: 5px; background: none;
+  font-size: 12.5px; color: inherit; cursor: pointer;
+}
+.xeplr-daterange-item:hover { background: var(--xeplr-hover, #f4f5f8); }
+.xeplr-daterange-item.on { color: var(--xeplr-accent, #4f5fd6); font-weight: 600; }
+.xeplr-daterange-body { padding: 10px; }
+.xeplr-daterange-field { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.xeplr-daterange-field span { width: 42px; flex-shrink: 0; font-size: 11.5px; color: var(--xeplr-muted, #6b7280); }
+.xeplr-daterange-field input,
+.xeplr-daterange-input {
+  flex: 1; min-width: 0; width: 100%; padding: 5px 8px;
+  border: 1px solid var(--xeplr-border, #e2e5eb); border-radius: 6px;
+  background: var(--xeplr-surface-2, #fafbfc); color: inherit; font-size: 12.5px;
+}
+.xeplr-daterange-note { font-size: 11px; color: var(--xeplr-muted-2, #9aa1ad); margin-top: 6px; line-height: 1.4; }
+.xeplr-daterange-foot {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 6px 10px; border-top: 1px solid var(--xeplr-border, #e2e5eb);
+}
+.xeplr-daterange-clear {
+  border: none; background: none; cursor: pointer;
+  font-size: 11.5px; font-weight: 600; color: var(--xeplr-accent, #4f5fd6);
+}
+.xeplr-daterange-current { font-size: 11px; color: var(--xeplr-muted-2, #9aa1ad); }
+.xeplr-daterange-inherited {
+  padding: 6px 10px; font-size: 10.5px; line-height: 1.4;
+  color: var(--xeplr-muted-2, #9aa1ad);
+  border-top: 1px solid var(--xeplr-border, #e2e5eb);
+}
+
+/* ── Suggestions, under the Single box ──────────────────────────────────── */
+.xeplr-daterange-suggest {
+  list-style: none; margin: 6px 0 0; padding: 0;
+  max-height: 190px; overflow: auto;
+  border: 1px solid var(--xeplr-border, #e2e5eb); border-radius: 8px;
+}
+.xeplr-daterange-suggest li + li { border-top: 1px solid var(--xeplr-border-secondary, #eef0f4); }
+.xeplr-daterange-suggest button {
+  display: flex; justify-content: space-between; align-items: baseline; gap: 10px;
+  width: 100%; padding: 7px 10px; border: 0; background: none;
+  font: inherit; font-size: 13px; color: var(--xeplr-text, #1c2029);
+  text-align: left; cursor: pointer;
+}
+.xeplr-daterange-suggest button:hover { background: var(--xeplr-hover, #f4f5f8); }
+.xeplr-daterange-suggest-note { font-size: 11px; color: var(--xeplr-muted, #6b7280); }

package/src/dateRange/designs/index.js

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

package/src/dateRange/pages.jsx

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

package/src/dateRange/useDateRangeController.js

@@ -0,0 +1,118 @@
+import { useEffect, useState } from 'react';
+import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions } from './dateRange.js';
+
+/**
+ * DateRange — controller. Owns which tab is open and the half-typed text; the
+ * design draws it. No JSX here.
+ *
+ * @param {object} props
+ * @param {object|null} props.value      - the current selection, or null
+ * @param {Function} props.onChange      - (selection|null) => void
+ * @param {Function} [props.onClose]     - called after a choice that ends the interaction
+ * @param {Array} [props.presets]        - override the quick list
+ * @param {boolean} [props.allowClear]   - default true. Set false where an
+ *   empty selection is not a state the host can accept — a report bounded by
+ *   a date, say, for which "no date" means scanning all of history.
+ */
+export function useDateRangeController(props) {
+  var value = props.value || null;
+  var onChange = props.onChange || function() {};
+  var onClose = props.onClose;
+  var presets = props.presets || QUICK_PRESETS;
+  // Opt-OUT, so every existing caller keeps the button it already had.
+  var allowClear = props.allowClear !== false;
+
+  var initial = value && value.kind ? value.kind : 'quick';
+  var tabState = useState(initial);
+  var tab = tabState[0];
+  var setTab = tabState[1];
+
+  var singleState = useState(value && value.kind === 'single' ? value.value : '');
+  var single = singleState[0];
+  var setSingle = singleState[1];
+
+  // A selection made elsewhere (a reset, a different record) has to show up
+  // here, or the box keeps displaying what the user last typed into it.
+  useEffect(function() {
+    if (value && value.kind === 'single') setSingle(value.value || '');
+  }, [value]);
+
+  var range = value && value.kind === 'range' ? value : { from: '', to: '' };
+  // Parsed as you type, so "May 202" reads as not-a-date-yet rather than
+  // silently saving as nothing.
+  var singleParsed = single ? parseSingleDate(single) : null;
+
+  // WHAT YEAR TO OFFER FIRST — the one already on screen.
+  //
+  // Somebody typing "j" after looking at Feb 2025 is almost certainly after a
+  // month of 2025. Read from what is COMMITTED rather than from what is being
+  // typed, or the anchor would move as soon as a suggestion resolved to a
+  // different year and the list would reorder under the cursor.
+  var committed = value && value.kind === 'single' ? parseSingleDate(value.value) : null;
+  var anchorYear = committed && committed.from
+    ? Number(String(committed.from).slice(0, 4))
+    : new Date().getFullYear();
+
+  var suggestions = singleDateSuggestions(single, anchorYear);
+
+  function applySuggestion(text) {
+    setSingle(text);
+    // COMMITTED IMMEDIATELY. Picking from a list is a decision — leaving it in
+    // the box for the user to then press Enter on would be asking twice.
+    if (parseSingleDate(text)) {
+      onChange({ kind: 'single', value: text });
+      if (onClose) onClose();
+    }
+  }
+
+  function selectPreset(key) {
+    onChange({ kind: 'quick', preset: key });
+    if (onClose) onClose();
+  }
+
+  function setRangeFrom(from) {
+    onChange({ kind: 'range', from: from, to: range.to || '' });
+  }
+
+  function setRangeTo(to) {
+    onChange({ kind: 'range', from: range.from || '', to: to });
+  }
+
+  // Only committed once it parses — a partial entry must not overwrite a good
+  // selection with nothing.
+  function commitSingle(close) {
+    if (!singleParsed) return;
+    onChange({ kind: 'single', value: single.trim() });
+    if (close && onClose) onClose();
+  }
+
+  function clear() {
+    // Enforced here, not only by hiding the button: a custom design that
+    // renders its own clear must not be able to produce a state the host
+    // said it cannot accept.
+    if (!allowClear) return;
+    onChange(null);
+    if (onClose) onClose();
+  }
+
+  return {
+    tab: tab,
+    setTab: setTab,
+    presets: presets,
+    value: value,
+    label: dateValueLabel(value),
+    range: range,
+    single: single,
+    setSingle: setSingle,
+    singleParsed: singleParsed,
+    suggestions: suggestions,
+    applySuggestion: applySuggestion,
+    selectPreset: selectPreset,
+    setRangeFrom: setRangeFrom,
+    setRangeTo: setRangeTo,
+    commitSingle: commitSingle,
+    clear: clear,
+    allowClear: allowClear,
+    inheritedLabel: props.inheritedLabel || null
+  };
+}

package/src/dateRange/validateDesign.js

@@ -0,0 +1,20 @@
+// A design that omits any of these can't collect a date, so the page reports
+// loudly at mount rather than rendering a control nobody can use.
+//
+// The tabs are the one thing always on screen. Everything else belongs to a
+// tab — the quick list to "Quick", the date inputs to "Range"/"Single" — so
+// requiring a preset list AND a date input at the same time is a rule no
+// tabbed design can satisfy on any tab. It failed every time it was mounted.
+// `anyOf` asks what is actually meant: is there some way to enter a date?
+export var DATE_RANGE_RULES = [
+  { selector: '.xeplr-daterange-tabs button, [data-xeplr-daterange-tab]', label: 'Tab buttons (quick / range / single)' },
+  {
+    anyOf: [
+      '.xeplr-daterange-list button',
+      '[data-xeplr-daterange-preset]',
+      'input[type="date"]',
+      '.xeplr-daterange-input'
+    ],
+    label: 'A way to pick a date — a quick preset list, or a date input'
+  }
+];

package/src/dropdown/designs/DropdownSample.jsx

@@ -0,0 +1,151 @@
+import './dropdown.css';
+
+function initials(name) {
+  if (!name) return '·';
+  var parts = String(name).trim().split(/\s+/).slice(0, 2);
+  return parts.map(function(p) { return p.charAt(0).toUpperCase(); }).join('');
+}
+
+function joinExtras(item, extras) {
+  var bits = [];
+  for (var i = 0; i < extras.length; i++) {
+    var v = item[extras[i]];
+    if (v != null && v !== '') bits.push(String(v));
+  }
+  return bits.join(' · ');
+}
+
+function summary(selectedItems, mode, keys, placeholder) {
+  if (selectedItems.length === 0) return <span className="xeplr-dropdown-placeholder">{placeholder}</span>;
+  if (mode === 'single') {
+    return <span className="xeplr-dropdown-selected-single">{selectedItems[0][keys.name]}</span>;
+  }
+  var first = selectedItems[0][keys.name];
+  var more = selectedItems.length - 1;
+  return (
+    <span className="xeplr-dropdown-selected-multi">
+      {first}{more > 0 ? <span className="xeplr-dropdown-selected-more"> +{more}</span> : null}
+    </span>
+  );
+}
+
+export default function DropdownSample({
+  mode, keys, searchable, placeholder, disabled,
+  filteredItems, selectedItems, loading, error, query, isOpen, rootRef,
+  isSelected, toggle, selectItem, removeSelection, clearSelection, handleSearch,
+  canCreate, createLabel, creating, createError, createItem
+}) {
+  var hasSelection = selectedItems.length > 0;
+  var trimmedQuery = (query || '').trim();
+  var exactMatch = filteredItems.some(function(item) {
+    return String(item[keys.name]).toLowerCase() === trimmedQuery.toLowerCase();
+  });
+  var showCreate = canCreate && trimmedQuery && !exactMatch;
+
+  return (
+    <div
+      ref={rootRef}
+      className={'xeplr-dropdown xeplr-dropdown-' + mode + (isOpen ? ' xeplr-dropdown-open' : '') + (disabled ? ' xeplr-dropdown-disabled' : '')}
+    >
+      <div
+        className="xeplr-dropdown-trigger"
+        role="combobox"
+        aria-expanded={isOpen}
+        onClick={toggle}
+      >
+        {mode === 'multi' && hasSelection ? (
+          <div className="xeplr-dropdown-chips">
+            {selectedItems.map(function(item) {
+              return (
+                <span key={item[keys.id]} className="xeplr-dropdown-chip">
+                  {item[keys.name]}
+                  <span
+                    className="xeplr-dropdown-chip-x"
+                    onClick={function(e) { e.stopPropagation(); removeSelection(item[keys.id]); }}
+                  >×</span>
+                </span>
+              );
+            })}
+          </div>
+        ) : summary(selectedItems, mode, keys, placeholder)}
+        <span className="xeplr-dropdown-caret">⌄</span>
+      </div>
+
+      <div
+        className={'xeplr-dropdown-panel' + (isOpen ? ' xeplr-dropdown-panel-open' : '')}
+        role="listbox"
+      >
+        {searchable && (
+          <div className="xeplr-dropdown-search">
+            <input
+              autoFocus
+              className="xeplr-dropdown-search-input"
+              placeholder="Search…"
+              value={query}
+              onChange={handleSearch}
+            />
+          </div>
+        )}
+
+        {loading && <div className="xeplr-dropdown-state">Loading…</div>}
+        {error && <div className="xeplr-dropdown-state xeplr-dropdown-state-error">{error}</div>}
+
+        {!loading && !error && filteredItems.length === 0 && !showCreate && (
+          <div className="xeplr-dropdown-state">
+            {canCreate && !trimmedQuery ? 'Type a name to add' : 'No matches'}
+          </div>
+        )}
+
+        {!loading && !error && filteredItems.map(function(item) {
+          var selected = isSelected(item[keys.id]);
+          var meta = joinExtras(item, keys.extras);
+          return (
+            <div
+              key={item[keys.id]}
+              role="option"
+              aria-selected={selected}
+              className={'xeplr-dropdown-row' + (selected ? ' xeplr-dropdown-row-selected' : '')}
+              onClick={function() { selectItem(item[keys.id]); }}
+            >
+              {mode === 'multi' && (
+                <span className={'xeplr-dropdown-check' + (selected ? ' xeplr-dropdown-check-on' : '')}>
+                  {selected ? '✓' : ''}
+                </span>
+              )}
+              <span className="xeplr-dropdown-avatar">{initials(item[keys.name])}</span>
+              <span className="xeplr-dropdown-info">
+                <span className="xeplr-dropdown-name">{item[keys.name]}</span>
+                {meta && <span className="xeplr-dropdown-meta">{meta}</span>}
+              </span>
+            </div>
+          );
+        })}
+
+        {showCreate && (
+          <div
+            role="option"
+            className="xeplr-dropdown-row xeplr-dropdown-create"
+            onClick={function() { if (!creating) createItem(); }}
+          >
+            <span className="xeplr-dropdown-avatar xeplr-dropdown-create-plus">＋</span>
+            <span className="xeplr-dropdown-info">
+              <span className="xeplr-dropdown-name">
+                {creating ? 'Adding…' : (createLabel + ' “' + trimmedQuery + '”')}
+              </span>
+            </span>
+          </div>
+        )}
+
+        {createError && (
+          <div className="xeplr-dropdown-state xeplr-dropdown-state-error">{createError}</div>
+        )}
+
+        {hasSelection && (
+          <div className="xeplr-dropdown-footer">
+            <span className="xeplr-dropdown-clear" onClick={clearSelection}>Clear selection</span>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}