@xeplr/ui-utils 1.0.0 → 1.0.2

package/src/gridDisplayer/designs/gridDisplayer.css

@@ -0,0 +1,89 @@
+/* Uses @xeplr/ui-account's --xeplr-* theme tokens when available (apply
+   .xeplr-theme-light/-dark on an ancestor); falls back to the original dark
+   hex values when that stylesheet isn't loaded. */
+
+.xeplr-grid-displayer {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  color: var(--xeplr-text-primary, #e0e0e0);
+}
+
+/* ─── Toolbar ─── */
+
+.xeplr-grid-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.xeplr-grid-search {
+  flex: 1;
+  max-width: 320px;
+  padding: 8px 12px;
+  border: 1px solid var(--xeplr-input-border, #3a3a3a);
+  border-radius: 8px;
+  background: var(--xeplr-input-bg, #141414);
+  color: var(--xeplr-input-text, #e0e0e0);
+  font-size: 14px;
+}
+.xeplr-grid-search:focus { outline: none; border-color: var(--xeplr-accent, #646cff); }
+
+/* One dropdown carries both field + direction (e.g. "Name (A-Z)") — no
+   separate asc/desc icon button to keep the toolbar clean. */
+.xeplr-grid-sort-select {
+  padding: 7px 10px;
+  border: 1px solid var(--xeplr-input-border, #3a3a3a);
+  border-radius: 8px;
+  background: var(--xeplr-input-bg, #141414);
+  color: var(--xeplr-input-text, #e0e0e0);
+  font-size: 13px;
+}
+
+/* ─── Grid + tiles ───
+   Netflix-style: a hovered tile scales up and lifts above its neighbors —
+   z-index only bumps on hover so it doesn't otherwise disturb grid stacking. */
+
+.xeplr-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: 16px;
+  /* room for hovered tiles to scale up without clipping against the container edge */
+  padding: 6px;
+}
+
+.xeplr-grid-tile {
+  position: relative;
+  border-radius: 14px;
+  background: var(--xeplr-bg-tertiary, #1a1a1a);
+  border: 1px solid var(--xeplr-border-secondary, #2a2a2a);
+  overflow: hidden;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease;
+  transform-origin: center;
+}
+
+.xeplr-grid-tile:hover {
+  transform: scale(1.08);
+  z-index: 5;
+  border-color: var(--xeplr-accent, #646cff);
+  box-shadow: var(--xeplr-shadow-lg, 0 12px 28px rgba(0, 0, 0, 0.45));
+}
+
+.xeplr-grid-tile-add {
+  border-style: dashed;
+  border-color: var(--xeplr-border-primary, #444);
+  display: grid;
+  place-items: center;
+  min-height: 120px;
+  color: var(--xeplr-text-muted, #888);
+}
+.xeplr-grid-tile-add:hover { border-color: var(--xeplr-accent, #646cff); color: var(--xeplr-text-primary, #e0e0e0); }
+
+.xeplr-grid-empty {
+  grid-column: 1 / -1;
+  padding: 32px;
+  text-align: center;
+  color: var(--xeplr-text-muted, #777);
+}

package/src/gridDisplayer/designs/index.js

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

package/src/gridDisplayer/gridDisplayer.js

@@ -0,0 +1,44 @@
+/**
+ * GridDisplayer — pure model. No React.
+ * Client-side search + sort over a plain `rows` array, same philosophy as
+ * CrudDisplayer/Dropdown — no fetch function, no server round-trip.
+ */
+
+/**
+ * Substring match (case-insensitive) across `searchFields`. A field whose
+ * value is an array (e.g. tags) matches if ANY entry contains the query.
+ */
+export function filterRows(rows, query, searchFields) {
+  if (!query) return rows || [];
+  var q = String(query).toLowerCase();
+  return (rows || []).filter(function(row) {
+    for (var i = 0; i < searchFields.length; i++) {
+      var value = row[searchFields[i]];
+      if (value == null) continue;
+      if (Array.isArray(value)) {
+        if (value.some(function(v) { return String(v).toLowerCase().indexOf(q) !== -1; })) return true;
+      } else if (String(value).toLowerCase().indexOf(q) !== -1) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
+
+function compareValues(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a).toLowerCase().localeCompare(String(b).toLowerCase());
+}
+
+export function sortRows(rows, field, direction) {
+  if (!field) return rows || [];
+  var copy = (rows || []).slice();
+  copy.sort(function(a, b) {
+    var result = compareValues(a[field], b[field]);
+    return direction === 'desc' ? -result : result;
+  });
+  return copy;
+}

package/src/gridDisplayer/pages.jsx

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

package/src/gridDisplayer/useGridDisplayerController.js

@@ -0,0 +1,59 @@
+import { useState, useMemo } from 'react';
+import { filterRows, sortRows } from './gridDisplayer.js';
+
+// Module-level (not recreated per render) — used as fallbacks below so a
+// caller that omits rows/searchFields/sortFields doesn't hand displayRows'
+// useMemo a fresh array identity every render, which would defeat the memo.
+var DEFAULT_ROWS = [];
+var DEFAULT_SEARCH_FIELDS = ['name'];
+// Each sortFields entry is a fully-resolved sort choice — field + direction
+// + label combined into one dropdown option (e.g. "Name (A-Z)") rather than
+// a bare field name paired with a separate asc/desc toggle button. One
+// dropdown, no extra icon button to keep clean.
+var DEFAULT_SORT_FIELDS = [{ value: 'name_asc', label: 'Name (A-Z)', field: 'name', direction: 'asc' }];
+
+/**
+ * @param {object} props
+ * @param {Array<object>} props.rows
+ * @param {*} props.tileFormatComponent - component rendering a tile's CONTENT only
+ *   (the design owns the clickable/hover-zoom wrapper around it) — receives
+ *   { row } for a normal tile, or { isAddTile: true } for the leading "add new"
+ *   tile (only rendered when props.onAddNew is supplied).
+ * @param {Array<string>} [props.searchFields=['name']] - row fields the search box matches
+ * @param {Array<{value:string, label:string, field:string, direction:'asc'|'desc'}>} [props.sortFields]
+ *   - default: [{value:'name_asc', label:'Name (A-Z)', field:'name', direction:'asc'}]
+ * @param {(row:object)=>void} [props.onSelect] - tile click (non-add tile)
+ * @param {()=>void} [props.onAddNew] - if provided, a leading "add new" tile renders
+ */
+export function useGridDisplayerController(props) {
+  props = props || {};
+  var rows = props.rows || DEFAULT_ROWS;
+  var searchFields = props.searchFields || DEFAULT_SEARCH_FIELDS;
+  var sortFields = props.sortFields || DEFAULT_SORT_FIELDS;
+
+  var [query, setQuery] = useState('');
+  var [sortValue, setSortValue] = useState(sortFields[0] ? sortFields[0].value : null);
+
+  var activeSort = null;
+  for (var i = 0; i < sortFields.length; i++) {
+    if (sortFields[i].value === sortValue) { activeSort = sortFields[i]; break; }
+  }
+  if (!activeSort) activeSort = sortFields[0] || null;
+
+  var displayRows = useMemo(function() {
+    var filtered = filterRows(rows, query, searchFields);
+    return sortRows(filtered, activeSort ? activeSort.field : null, activeSort ? activeSort.direction : 'asc');
+  }, [rows, query, searchFields, activeSort]);
+
+  return {
+    query: query,
+    setQuery: setQuery,
+    sortFields: sortFields,
+    sortValue: activeSort ? activeSort.value : null,
+    setSortValue: setSortValue,
+    displayRows: displayRows,
+    tileFormatComponent: props.tileFormatComponent,
+    onSelect: props.onSelect,
+    onAddNew: props.onAddNew
+  };
+}

package/src/gridDisplayer/validateDesign.js

@@ -0,0 +1,4 @@
+export var GRID_DISPLAYER_RULES = [
+  { selector: '.xeplr-grid-search', label: 'Search input' },
+  { selector: '.xeplr-grid', label: 'Tile grid' }
+];

package/src/index.js

@@ -10,14 +10,190 @@ export { useDesignValidator, FILE_UPLOAD_RULES } from './fileUpload/validateDesi
 // File Upload — sample design
 export { FileUploadSample } from './fileUpload/designs/index.js';
 
-// File Upload — ready-made page (controller + sample design wired)
+// File Upload — ready-made page
 export { FileUploadPage } from './fileUpload/pages.jsx';
 
+// DataImport — model. Upload a file, map its parts (e.g. Excel sheets — or
+// the whole file, for CSV/JSON) to app-defined named targets, commit. The
+// app supplies onInspect/onCommit (its own upload + load endpoints); this
+// module only owns the file-pick -> mapping -> commit flow and UI.
+export { sanitizeTargetName, buildInitialMappings } from './dataImport/dataImport.js';
+
+// DataImport — controller
+export { useDataImportController } from './dataImport/useDataImportController.js';
+
+// DataImport — design validation
+export { DATA_IMPORT_RULES } from './dataImport/validateDesign.js';
+
+// DataImport — sample design
+export { DataImportSample } from './dataImport/designs/index.js';
+
+// DataImport — ready-made page
+export { DataImportPage } from './dataImport/pages.jsx';
+
+// ImportHistory — lists past import jobs (app-supplied onList) with a
+// Rollback action per row (app-supplied onRollback) — the read/undo side of
+// DataImportPage's write side, same file/model. Product-agnostic: the app
+// owns what "list" and "rollback" actually call.
+export { useImportHistoryController } from './dataImport/useImportHistoryController.js';
+export { IMPORT_HISTORY_RULES } from './dataImport/validateDesign.js';
+export { ImportHistorySample } from './dataImport/designs/index.js';
+export { ImportHistoryPage } from './dataImport/pages.jsx';
+
+// NumberField — model
+export {
+  NUMBER_TYPES,
+  sanitizeNumberInput,
+  toNumeric,
+  formatDisplay,
+  validateRange,
+  resolveAffixState
+} from './numberField/numberField.js';
+
+// NumberField — controller
+export { useNumberFieldController } from './numberField/useNumberFieldController.js';
+
+// NumberField — design validation
+export { NUMBER_FIELD_RULES } from './numberField/validateDesign.js';
+
+// NumberField — sample design
+export { NumberFieldSample } from './numberField/designs/index.js';
+
+// NumberField — ready-made page
+export { NumberFieldPage } from './numberField/pages.jsx';
+
+// DateField — model
+export {
+  DATE_TYPES,
+  isValidISODate,
+  calculateAge,
+  inputTypeFor,
+  toInputValue,
+  validateBounds
+} from './dateField/dateField.js';
+
+// DateField — controller
+export { useDateFieldController } from './dateField/useDateFieldController.js';
+
+// DateField — design validation
+export { DATE_FIELD_RULES } from './dateField/validateDesign.js';
+
+// DateField — sample design
+export { DateFieldSample } from './dateField/designs/index.js';
+
+// DateField — ready-made page
+export { DateFieldPage } from './dateField/pages.jsx';
+
+// DateRange — model. One selection covering a quick preset, an explicit
+// range, or a single day/month/year; everything resolves to {from, to}.
+export {
+  QUICK_PRESETS,
+  parseSingleDate,
+  resolveQuickPreset,
+  resolveDateValue,
+  dateValueLabel,
+  dateValueIsSet
+} from './dateRange/dateRange.js';
+
+// DateRange — controller
+export { useDateRangeController } from './dateRange/useDateRangeController.js';
+
+// DateRange — design validation
+export { DATE_RANGE_RULES } from './dateRange/validateDesign.js';
+
+// DateRange — sample design
+export { DateRangeSample } from './dateRange/designs/index.js';
+
+// DateRange — ready-made page
+export { DateRangePage } from './dateRange/pages.jsx';
+
+// RangeField — model. Not DateRange (below) — that's a full quick/range/
+// single POPOVER picker; this is just a From+To pair rendered as one field,
+// for a caller that already knows it wants an explicit range and has
+// nowhere to put a popover.
+export { RANGE_TYPES, emptyRange, normalizeRange, rangeIsSet } from './rangeField/rangeField.js';
+
+// RangeField — controller
+export { useRangeFieldController } from './rangeField/useRangeFieldController.js';
+
+// RangeField — design validation
+export { RANGE_FIELD_RULES } from './rangeField/validateDesign.js';
+
+// RangeField — sample design
+export { RangeFieldSample } from './rangeField/designs/index.js';
+
+// RangeField — ready-made page
+export { RangeFieldPage } from './rangeField/pages.jsx';
+
+// Dropdown — model
+export {
+  DROPDOWN_MODES,
+  normalizeKeys,
+  sortByKey,
+  filterByQuery,
+  pickSelected
+} from './dropdown/dropdown.js';
+
+// Dropdown — controller
+export { useDropdownController } from './dropdown/useDropdownController.js';
+
+// Dropdown — design validation
+export { DROPDOWN_RULES } from './dropdown/validateDesign.js';
+
+// Dropdown — sample design
+export { DropdownSample } from './dropdown/designs/index.js';
+
+// Dropdown — ready-made page
+export { DropdownPage } from './dropdown/pages.jsx';
+
+// GridDisplayer — model
+export { filterRows as filterGridRows, sortRows as sortGridRows } from './gridDisplayer/gridDisplayer.js';
+
+// GridDisplayer — controller
+export { useGridDisplayerController } from './gridDisplayer/useGridDisplayerController.js';
+
+// GridDisplayer — design validation
+export { GRID_DISPLAYER_RULES } from './gridDisplayer/validateDesign.js';
+
+// GridDisplayer — sample design
+export { GridDisplayerSample } from './gridDisplayer/designs/index.js';
+
+// GridDisplayer — ready-made page
+export { GridDisplayerPage } from './gridDisplayer/pages.jsx';
+
 // Snackbar
 export { raiseSnackbar } from './snackbar/snackbar.js';
 
+// Confirm
+export { raiseConfirm, raiseChoice } from './confirm/confirm.js';
+
+// Theme — brand-neutral DEFAULT design tokens (chart + table), override-friendly.
+// Consumers pass overrides to resolveTheme(); overrides win, rest falls through.
+export { default as DEFAULT_THEME, resolveTheme, getThemeVariant, getChartOptions, inputStyleVars, deepMerge } from './theme/index.js';
+
 // Static data
 export { default as COUNTRIES } from './data/countries.json';
 import _statesData from './data/states.json';
 export var STATES = _statesData.STATES;
 export var STATES_IN = _statesData.STATES_IN;
+
+// TextField — the plain text input, its multiline and search shapes.
+export { TEXT_TYPES, toValue, normalise, validate, remaining } from './textField/textField.js';
+export { useTextFieldController } from './textField/useTextFieldController.js';
+export { TEXT_FIELD_RULES } from './textField/validateDesign.js';
+export { TextFieldSample } from './textField/designs/index.js';
+export { TextFieldPage } from './textField/pages.jsx';
+
+// ── Progress notifier ────────────────────────────────────────────────────
+//
+// A small moving bar and a line of text, driven by an event KEY the back end
+// chooses. Hidden until an event for that key arrives, so it is safe to mount
+// on anything; visible while the work says it is continuing.
+//
+// An app attaches its own stream ONCE with attachProgressSource, adapting
+// whatever it publishes into { key, continue, status?, data }. This package
+// knows nothing about SSE — see progressSource.js for why the sentence is
+// built on the client rather than sent as prose.
+export { attachProgressSource, progressSourceAttached, subscribeToProgress,
+         describeProgress, describeComplete } from './progress/progressSource.js';
+export { default as ProgressNotifier } from './progress/ProgressNotifier.jsx';

package/src/numberField/designs/NumberFieldSample.jsx

@@ -0,0 +1,52 @@
+import './numberField.css';
+
+export default function NumberFieldSample({
+  type, raw, error, placeholder, disabled, affix,
+  handleNumberChange, handleAffixChange, handleBlur
+}) {
+  function renderAffix() {
+    if (!affix) return null;
+    if (affix.list.length === 1) {
+      return <span className="xeplr-numberfield-affix-static">{affix.selected[affix.labelKey]}</span>;
+    }
+    return (
+      <select
+        className="xeplr-numberfield-affix-select"
+        value={affix.selected[affix.valueKey]}
+        onChange={handleAffixChange}
+        disabled={disabled}
+      >
+        {affix.list.map(function(item) {
+          return (
+            <option key={item[affix.valueKey]} value={item[affix.valueKey]}>
+              {item[affix.labelKey]}
+            </option>
+          );
+        })}
+      </select>
+    );
+  }
+
+  var affixBefore = affix && affix.position === 'before';
+  var affixAfter = affix && affix.position === 'after';
+
+  return (
+    <div className={'xeplr-numberfield xeplr-numberfield-' + type + (error ? ' xeplr-numberfield-error' : '')}>
+      <div className="xeplr-numberfield-row">
+        {affixBefore && renderAffix()}
+        <input
+          type="text"
+          inputMode="decimal"
+          className="xeplr-numberfield-input"
+          value={raw}
+          placeholder={placeholder}
+          disabled={disabled}
+          onChange={handleNumberChange}
+          onBlur={handleBlur}
+        />
+        {affixAfter && renderAffix()}
+      </div>
+      {error && <div className="xeplr-numberfield-error-text">{error}</div>}
+    </div>
+  );
+}

package/src/numberField/designs/index.js

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

package/src/numberField/designs/numberField.css

@@ -0,0 +1,66 @@
+.xeplr-numberfield {
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #e0e0e0;
+}
+
+.xeplr-numberfield-row {
+  display: flex;
+  align-items: stretch;
+  border: 1px solid #444;
+  border-radius: 6px;
+  background: #1a1a1a;
+  overflow: hidden;
+}
+
+.xeplr-numberfield-row:focus-within {
+  border-color: #646cff;
+  box-shadow: 0 0 0 2px rgba(100, 108, 255, 0.18);
+}
+
+.xeplr-numberfield-error .xeplr-numberfield-row {
+  border-color: #e25555;
+}
+
+.xeplr-numberfield-input {
+  flex: 1;
+  background: transparent;
+  border: none;
+  outline: none;
+  color: inherit;
+  padding: 9px 12px;
+  font-size: 14px;
+  min-width: 0;
+}
+
+.xeplr-numberfield-affix-select,
+.xeplr-numberfield-affix-static {
+  background: #232540;
+  border: none;
+  color: #b8bbe0;
+  padding: 0 12px;
+  font-size: 13px;
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+  outline: none;
+}
+
+.xeplr-numberfield-affix-static {
+  cursor: default;
+}
+
+.xeplr-numberfield-row > .xeplr-numberfield-affix-select:first-child,
+.xeplr-numberfield-row > .xeplr-numberfield-affix-static:first-child {
+  border-right: 1px solid #444;
+}
+
+.xeplr-numberfield-row > .xeplr-numberfield-affix-select:last-child,
+.xeplr-numberfield-row > .xeplr-numberfield-affix-static:last-child {
+  border-left: 1px solid #444;
+}
+
+.xeplr-numberfield-error-text {
+  margin-top: 4px;
+  font-size: 12px;
+  color: #e25555;
+}

package/src/numberField/numberField.js

@@ -0,0 +1,105 @@
+/**
+ * NumberField — pure model. No React.
+ *
+ * Handles the parsing, formatting, and validation of numeric input.
+ * Three flavours of value: float, currency, units. Currency and units
+ * are numerically the same — they only differ by the affix shown next
+ * to the number (a dropdown of currencies or a dropdown of units).
+ */
+
+export var NUMBER_TYPES = ['float', 'currency', 'units'];
+
+/**
+ * Strip everything that isn't a digit, decimal point, or leading minus.
+ * Collapses multiple decimal points to the first one.
+ */
+export function sanitizeNumberInput(raw) {
+  if (raw === null || raw === undefined) return '';
+  var str = String(raw);
+  var negative = str.charAt(0) === '-';
+  str = str.replace(/[^0-9.]/g, '');
+  var parts = str.split('.');
+  if (parts.length > 2) {
+    str = parts[0] + '.' + parts.slice(1).join('');
+  }
+  return (negative ? '-' : '') + str;
+}
+
+/**
+ * Convert a raw string to a Number. Returns null if not a finite number.
+ */
+export function toNumeric(raw) {
+  if (raw === null || raw === undefined || raw === '' || raw === '-') return null;
+  var n = Number(raw);
+  return isFinite(n) ? n : null;
+}
+
+/**
+ * Format a numeric value for display. Locale-aware grouping.
+ */
+export function formatDisplay(value, decimals) {
+  if (value === null || value === undefined || value === '') return '';
+  var n = Number(value);
+  if (!isFinite(n)) return '';
+  if (typeof decimals === 'number') {
+    return n.toLocaleString(undefined, {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals
+    });
+  }
+  return n.toLocaleString();
+}
+
+/**
+ * Validate a numeric value against optional min/max bounds.
+ * Returns { valid: true } or { valid: false, error: string }.
+ */
+export function validateRange(value, min, max) {
+  if (value === null) return { valid: true };
+  if (typeof min === 'number' && value < min) {
+    return { valid: false, error: 'Value must be at least ' + min };
+  }
+  if (typeof max === 'number' && value > max) {
+    return { valid: false, error: 'Value must be at most ' + max };
+  }
+  return { valid: true };
+}
+
+/**
+ * Resolve the affix list and currently-selected affix for a given type.
+ * Falls back to a sensible default when the user supplied only one item.
+ */
+export function resolveAffixState(type, options) {
+  options = options || {};
+  if (type === 'currency') {
+    var currencies = options.currencies || [];
+    if (currencies.length === 0) {
+      throw new Error('[xeplr-ui-utils:NumberField] type="currency" requires a `currencies` prop with at least one entry like { code: "INR", symbol: "₹" }');
+    }
+    var defaultCode = options.defaultCurrency || currencies[0].code;
+    var selected = currencies.find(function(c) { return c.code === defaultCode; }) || currencies[0];
+    return {
+      list: currencies,
+      selected: selected,
+      position: options.currencyPosition || 'before',
+      labelKey: 'symbol',
+      valueKey: 'code'
+    };
+  }
+  if (type === 'units') {
+    var units = options.units || [];
+    if (units.length === 0) {
+      throw new Error('[xeplr-ui-utils:NumberField] type="units" requires a `units` prop with at least one entry like { value: "kg", label: "kg" }');
+    }
+    var defaultValue = options.defaultUnit || units[0].value;
+    var selectedUnit = units.find(function(u) { return u.value === defaultValue; }) || units[0];
+    return {
+      list: units,
+      selected: selectedUnit,
+      position: options.unitPosition || 'after',
+      labelKey: 'label',
+      valueKey: 'value'
+    };
+  }
+  return null;
+}

package/src/numberField/pages.jsx

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