@xeplr/ui-utils 1.0.0 → 1.0.1

package/src/dataImport/validateDesign.js

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Validates that required elements exist in the rendered design.
+ * Throws a visible error if any required element is missing.
+ *
+ * @param {string} componentName - Name of the page (for error messages)
+ * @param {Array<{id?: string, role?: string, selector?: string, label: string}>} requiredElements
+ */
+export function useDesignValidator(componentName, requiredElements) {
+  var containerRef = useRef(null);
+
+  useEffect(function() {
+    if (!containerRef.current) return;
+
+    var missing = [];
+    for (var i = 0; i < requiredElements.length; i++) {
+      var rule = requiredElements[i];
+      var found = false;
+
+      if (rule.id) {
+        found = !!containerRef.current.querySelector('#' + rule.id);
+      } else if (rule.role) {
+        found = !!containerRef.current.querySelector('[role="' + rule.role + '"]');
+      } else if (rule.selector) {
+        found = !!containerRef.current.querySelector(rule.selector);
+      }
+
+      if (!found) {
+        missing.push(rule.label + (rule.id ? ' (id="' + rule.id + '")' : '') + (rule.selector ? ' (' + rule.selector + ')' : ''));
+      }
+    }
+
+    if (missing.length > 0) {
+      throw new Error(
+        '[xeplr-ui-utils] ' + componentName + ' design is missing required elements:\n' +
+        missing.map(function(m) { return '  - ' + m; }).join('\n')
+      );
+    }
+  }, []);
+
+  return containerRef;
+}
+
+export var DATA_IMPORT_RULES = [
+  { selector: 'input[type="file"]', label: 'File input' }
+];
+
+export var IMPORT_HISTORY_RULES = [];

package/src/dateField/dateField.js

@@ -0,0 +1,71 @@
+/**
+ * DateField — pure model. No React.
+ *
+ * Three flavours:
+ *   - 'date'     → ISO date string (YYYY-MM-DD)
+ *   - 'datetime' → ISO datetime string (YYYY-MM-DDTHH:mm)
+ *   - 'age'      → input is a DOB (date), output value is the DOB but the
+ *                  age in years is computed and returned alongside.
+ */
+
+export var DATE_TYPES = ['date', 'datetime', 'age'];
+
+export function isValidISODate(s) {
+  if (typeof s !== 'string' || s.length === 0) return false;
+  var d = new Date(s);
+  return !isNaN(d.getTime());
+}
+
+/**
+ * Calculate completed years between dob and `now`. Returns null if dob is invalid.
+ */
+export function calculateAge(dob, now) {
+  if (!dob) return null;
+  var birth = dob instanceof Date ? dob : new Date(dob);
+  if (isNaN(birth.getTime())) return null;
+  var ref = now || new Date();
+  var years = ref.getFullYear() - birth.getFullYear();
+  var monthDiff = ref.getMonth() - birth.getMonth();
+  if (monthDiff < 0 || (monthDiff === 0 && ref.getDate() < birth.getDate())) {
+    years--;
+  }
+  return years < 0 ? null : years;
+}
+
+/**
+ * Map our public type to the underlying <input> type attribute.
+ */
+export function inputTypeFor(type) {
+  if (type === 'datetime') return 'datetime-local';
+  return 'date';
+}
+
+/**
+ * Normalise a Date or string into the format the <input> element expects.
+ */
+export function toInputValue(value, type) {
+  if (!value) return '';
+  var d = value instanceof Date ? value : new Date(value);
+  if (isNaN(d.getTime())) return '';
+  var pad = function(n) { return n < 10 ? '0' + n : '' + n; };
+  var ymd = d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate());
+  if (type === 'datetime') {
+    return ymd + 'T' + pad(d.getHours()) + ':' + pad(d.getMinutes());
+  }
+  return ymd;
+}
+
+export function validateBounds(value, min, max) {
+  if (!value) return { valid: true };
+  var d = value instanceof Date ? value : new Date(value);
+  if (isNaN(d.getTime())) return { valid: false, error: 'Invalid date' };
+  if (min) {
+    var dMin = min instanceof Date ? min : new Date(min);
+    if (d < dMin) return { valid: false, error: 'Date is before minimum' };
+  }
+  if (max) {
+    var dMax = max instanceof Date ? max : new Date(max);
+    if (d > dMax) return { valid: false, error: 'Date is after maximum' };
+  }
+  return { valid: true };
+}

package/src/dateField/designs/DateFieldSample.jsx

@@ -0,0 +1,30 @@
+import './dateField.css';
+
+export default function DateFieldSample({
+  type, inputType, raw, age, error, placeholder, disabled, min, max,
+  handleChange
+}) {
+  return (
+    <div className={'xeplr-datefield xeplr-datefield-' + type + (error ? ' xeplr-datefield-error' : '')}>
+      <div className="xeplr-datefield-row">
+        <input
+          type={inputType}
+          className="xeplr-datefield-input"
+          value={raw}
+          placeholder={placeholder}
+          disabled={disabled}
+          min={min}
+          max={max}
+          onChange={handleChange}
+        />
+        {type === 'age' && (
+          <div className="xeplr-datefield-age">
+            <span className="xeplr-datefield-age-label">Age</span>
+            <span className="xeplr-datefield-age-value">{age === null ? '—' : age + ' yrs'}</span>
+          </div>
+        )}
+      </div>
+      {error && <div className="xeplr-datefield-error-text">{error}</div>}
+    </div>
+  );
+}

package/src/dateField/designs/dateField.css

@@ -0,0 +1,60 @@
+.xeplr-datefield {
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #e0e0e0;
+}
+
+.xeplr-datefield-row {
+  display: flex;
+  align-items: stretch;
+  gap: 10px;
+}
+
+.xeplr-datefield-input {
+  flex: 1;
+  background: #1a1a1a;
+  border: 1px solid #444;
+  border-radius: 6px;
+  padding: 9px 12px;
+  color: inherit;
+  font-size: 14px;
+  outline: none;
+  color-scheme: dark;
+}
+
+.xeplr-datefield-input:focus {
+  border-color: #646cff;
+  box-shadow: 0 0 0 2px rgba(100, 108, 255, 0.18);
+}
+
+.xeplr-datefield-error .xeplr-datefield-input {
+  border-color: #e25555;
+}
+
+.xeplr-datefield-age {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  background: #232540;
+  border-radius: 6px;
+  padding: 4px 14px;
+  min-width: 90px;
+}
+
+.xeplr-datefield-age-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: #888bbf;
+}
+
+.xeplr-datefield-age-value {
+  font-size: 14px;
+  font-weight: 600;
+  color: #e0e0e0;
+}
+
+.xeplr-datefield-error-text {
+  margin-top: 4px;
+  font-size: 12px;
+  color: #e25555;
+}

package/src/dateField/designs/index.js

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

package/src/dateField/pages.jsx

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

package/src/dateField/useDateFieldController.js

@@ -0,0 +1,77 @@
+import { useState, useEffect, useMemo } from 'react';
+import {
+  DATE_TYPES,
+  calculateAge,
+  inputTypeFor,
+  toInputValue,
+  validateBounds
+} from './dateField.js';
+
+/**
+ * @param {object} props
+ * @param {'date'|'datetime'|'age'} [props.type='date']
+ * @param {Date|string|null} [props.value]        — controlled value
+ * @param {Date|string|null} [props.defaultValue] — uncontrolled initial value
+ * @param {(value, meta) => void} [props.onChange] — meta.age included for age type
+ * @param {Date|string} [props.min]
+ * @param {Date|string} [props.max]
+ * @param {string} [props.placeholder]
+ * @param {boolean} [props.disabled]
+ */
+export function useDateFieldController(props) {
+  props = props || {};
+  var type = props.type || 'date';
+  if (DATE_TYPES.indexOf(type) === -1) {
+    throw new Error('[xeplr-ui-utils:DateField] Unknown type: ' + type + '. Expected one of ' + DATE_TYPES.join(', '));
+  }
+
+  var isControlled = props.value !== undefined;
+  var initial = isControlled ? props.value : (props.defaultValue !== undefined ? props.defaultValue : null);
+
+  var [raw, setRaw] = useState(toInputValue(initial, type === 'age' ? 'date' : type));
+  var [error, setError] = useState('');
+
+  useEffect(function() {
+    if (isControlled) {
+      setRaw(toInputValue(props.value, type === 'age' ? 'date' : type));
+    }
+  }, [props.value, isControlled, type]);
+
+  var inputType = useMemo(function() {
+    return inputTypeFor(type === 'age' ? 'date' : type);
+  }, [type]);
+
+  var age = useMemo(function() {
+    if (type !== 'age') return null;
+    return calculateAge(raw);
+  }, [type, raw]);
+
+  function emit(nextRaw) {
+    var bounds = validateBounds(nextRaw, props.min, props.max);
+    setError(bounds.valid ? '' : bounds.error);
+    if (props.onChange) {
+      var meta = {};
+      if (type === 'age') meta.age = calculateAge(nextRaw);
+      props.onChange(nextRaw || null, meta);
+    }
+  }
+
+  function handleChange(e) {
+    var v = e.target.value;
+    if (!isControlled) setRaw(v);
+    emit(v);
+  }
+
+  return {
+    type,
+    inputType,
+    raw,
+    age,
+    error,
+    placeholder: props.placeholder,
+    disabled: !!props.disabled,
+    min: props.min ? toInputValue(props.min, type === 'age' ? 'date' : type) : undefined,
+    max: props.max ? toInputValue(props.max, type === 'age' ? 'date' : type) : undefined,
+    handleChange
+  };
+}

package/src/dateField/validateDesign.js

@@ -0,0 +1,3 @@
+export var DATE_FIELD_RULES = [
+  { selector: 'input[type="date"], input[type="datetime-local"], input.xeplr-datefield-input', label: 'Date input element' }
+];

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

package/src/dropdown/designs/dropdown.css

@@ -0,0 +1,226 @@
+/* Uses @xeplr/ui-account's --xeplr-* theme tokens when available (see
+   xeplr-ui-account/src/designs/theme.css — apply .xeplr-theme-light/-dark on
+   an ancestor to pick a theme); falls back to the original dark hex values
+   when that stylesheet isn't loaded, so this still renders sensibly standalone. */
+
+.xeplr-dropdown {
+  position: relative;
+  font-family: system-ui, -apple-system, sans-serif;
+  color: var(--xeplr-text-primary, #e0e0e0);
+}
+
+.xeplr-dropdown-trigger {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 40px;
+  background: var(--xeplr-input-bg, #1a1a1a);
+  border: 1px solid var(--xeplr-input-border, #444);
+  border-radius: 6px;
+  padding: 6px 10px 6px 12px;
+  cursor: pointer;
+  font-size: 14px;
+  color: var(--xeplr-input-text, #e0e0e0);
+}
+
+.xeplr-dropdown-open .xeplr-dropdown-trigger {
+  border-color: var(--xeplr-accent, #646cff);
+  box-shadow: 0 0 0 2px rgba(100, 108, 255, 0.18);
+}
+
+.xeplr-dropdown-disabled .xeplr-dropdown-trigger {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.xeplr-dropdown-placeholder { color: var(--xeplr-input-placeholder, #888); flex: 1; }
+.xeplr-dropdown-selected-single { flex: 1; }
+.xeplr-dropdown-selected-multi { flex: 1; }
+.xeplr-dropdown-selected-more { color: var(--xeplr-text-secondary, #888bbf); margin-left: 6px; font-size: 12px; }
+
+.xeplr-dropdown-caret {
+  margin-left: auto;
+  color: var(--xeplr-text-muted, #888);
+  font-size: 14px;
+}
+
+.xeplr-dropdown-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  flex: 1;
+}
+
+.xeplr-dropdown-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--xeplr-tag-bg, #232540);
+  border-radius: 999px;
+  padding: 3px 4px 3px 10px;
+  font-size: 12px;
+  color: var(--xeplr-tag-text, #c8cbe8);
+}
+
+.xeplr-dropdown-chip-x {
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  background: var(--xeplr-bg-primary, #1a1a1a);
+  display: grid;
+  place-items: center;
+  cursor: pointer;
+  font-size: 12px;
+  line-height: 1;
+}
+
+.xeplr-dropdown-chip-x:hover { background: var(--xeplr-danger, #e25555); color: var(--xeplr-accent-text, #fff); }
+
+.xeplr-dropdown-panel {
+  display: none;
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 0;
+  right: 0;
+  background: var(--xeplr-bg-tertiary, #141625);
+  border: 1px solid var(--xeplr-border-primary, #444);
+  border-radius: 6px;
+  box-shadow: var(--xeplr-shadow-lg, 0 10px 30px rgba(0, 0, 0, 0.55));
+  z-index: 50;
+  overflow: hidden;
+  max-height: 360px;
+  overflow-y: auto;
+}
+
+.xeplr-dropdown-panel-open { display: block; }
+
+.xeplr-dropdown-search {
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--xeplr-border-secondary, #2a2d44);
+  background: var(--xeplr-bg-secondary, #1a1c30);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+
+.xeplr-dropdown-search-input {
+  width: 100%;
+  background: var(--xeplr-input-bg, #0e0f1c);
+  border: 1px solid var(--xeplr-input-border, #2a2d44);
+  border-radius: 4px;
+  color: var(--xeplr-input-text, #e0e0e0);
+  padding: 7px 10px;
+  font-size: 13px;
+  outline: none;
+}
+
+.xeplr-dropdown-search-input:focus {
+  border-color: var(--xeplr-accent, #646cff);
+}
+
+.xeplr-dropdown-state {
+  padding: 14px 16px;
+  color: var(--xeplr-text-secondary, #888bbf);
+  font-size: 13px;
+  text-align: center;
+}
+
+.xeplr-dropdown-state-error { color: var(--xeplr-danger, #e25555); }
+
+.xeplr-dropdown-row {
+  display: grid;
+  grid-template-columns: auto 32px 1fr;
+  gap: 10px;
+  align-items: center;
+  padding: 9px 12px;
+  cursor: pointer;
+  border-bottom: 1px solid var(--xeplr-border-secondary, #1f2236);
+}
+
+.xeplr-dropdown-single .xeplr-dropdown-row {
+  grid-template-columns: 32px 1fr;
+}
+
+.xeplr-dropdown-row:hover { background: var(--xeplr-bg-hover, #1c1f33); }
+.xeplr-dropdown-row-selected { background: var(--xeplr-bg-active, rgba(100, 108, 255, 0.13)); }
+
+.xeplr-dropdown-check {
+  width: 16px;
+  height: 16px;
+  border-radius: 4px;
+  border: 1.5px solid var(--xeplr-input-border, #444);
+  background: var(--xeplr-input-bg, #0e0f1c);
+  display: grid;
+  place-items: center;
+  font-size: 11px;
+  color: transparent;
+}
+
+.xeplr-dropdown-check-on {
+  background: var(--xeplr-accent, #646cff);
+  border-color: var(--xeplr-accent, #646cff);
+  color: var(--xeplr-accent-text, #fff);
+}
+
+.xeplr-dropdown-avatar {
+  width: 30px;
+  height: 30px;
+  border-radius: 50%;
+  background: var(--xeplr-tag-bg, #232540);
+  color: var(--xeplr-tag-text, #b8bbe0);
+  display: grid;
+  place-items: center;
+  font-size: 11px;
+  font-weight: 700;
+}
+
+.xeplr-dropdown-info {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.xeplr-dropdown-name {
+  font-size: 13px;
+  color: var(--xeplr-text-primary, #e6e8f5);
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.xeplr-dropdown-meta {
+  font-size: 11px;
+  color: var(--xeplr-text-secondary, #888bbf);
+  margin-top: 2px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.xeplr-dropdown-footer {
+  padding: 8px 12px;
+  border-top: 1px solid var(--xeplr-border-secondary, #2a2d44);
+  background: var(--xeplr-bg-secondary, #1a1c30);
+  text-align: right;
+}
+
+.xeplr-dropdown-clear {
+  font-size: 12px;
+  color: var(--xeplr-text-secondary, #888bbf);
+  cursor: pointer;
+}
+
+.xeplr-dropdown-clear:hover { color: var(--xeplr-danger, #e25555); }
+
+.xeplr-dropdown-create {
+  border-top: 1px solid var(--xeplr-border-secondary, #2a2d44);
+  color: var(--xeplr-accent, #9fb2ff);
+}
+.xeplr-dropdown-create:hover { background: var(--xeplr-bg-hover, #232744); }
+.xeplr-dropdown-create .xeplr-dropdown-name { color: var(--xeplr-accent, #9fb2ff); font-weight: 600; }
+.xeplr-dropdown-create-plus {
+  background: var(--xeplr-tag-bg, #2a2f52);
+  color: var(--xeplr-accent, #9fb2ff);
+  font-weight: 700;
+}

package/src/dropdown/designs/index.js

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