@xeplr/ui-utils 1.0.0 → 1.0.1

package/src/dropdown/dropdown.js

@@ -0,0 +1,75 @@
+/**
+ * Dropdown — pure model. No React.
+ *
+ * Two sources:
+ *   - 'static'  → caller passes `options` directly
+ *   - 'dynamic' → caller passes `fetchData` (returns Promise<Array>)
+ *
+ * Two modes: 'single' or 'multi'.
+ *
+ * Items default to { id, name }. Other shapes are supported via the `keys`
+ * prop, an array where keys[0] is the id field, keys[1] is the display name
+ * (also used for sort + search), and the remainder are "extra" fields shown
+ * as metadata in each row (also searchable).
+ */
+
+export var DROPDOWN_MODES = ['single', 'multi'];
+
+/**
+ * Turn a `keys` array (or undefined) into a structured shape.
+ * keys[0] = id, keys[1] = name, keys[2..] = extras.
+ */
+export function normalizeKeys(keys) {
+  var arr = Array.isArray(keys) && keys.length >= 2 ? keys : ['id', 'name'];
+  return {
+    id: arr[0],
+    name: arr[1],
+    extras: arr.slice(2)
+  };
+}
+
+/**
+ * Sort items ascending by the named key, case-insensitive for strings.
+ */
+export function sortByKey(items, key) {
+  if (!Array.isArray(items)) return [];
+  var copy = items.slice();
+  copy.sort(function(a, b) {
+    var av = a == null ? '' : a[key];
+    var bv = b == null ? '' : b[key];
+    if (typeof av === 'string') av = av.toLowerCase();
+    if (typeof bv === 'string') bv = bv.toLowerCase();
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+    return 0;
+  });
+  return copy;
+}
+
+/**
+ * Filter items where any of `searchKeys` contains `query` (case-insensitive).
+ * Empty query returns all items.
+ */
+export function filterByQuery(items, query, searchKeys) {
+  if (!query) return items;
+  var q = String(query).toLowerCase();
+  return items.filter(function(item) {
+    for (var i = 0; i < searchKeys.length; i++) {
+      var v = item[searchKeys[i]];
+      if (v != null && String(v).toLowerCase().indexOf(q) !== -1) return true;
+    }
+    return false;
+  });
+}
+
+/**
+ * Find items whose ids match the given selection.
+ * `selection` is an array of ids; returns an array of items in the same order
+ * as the master list (preserves stability across reorders).
+ */
+export function pickSelected(items, selection, idKey) {
+  if (!selection || selection.length === 0) return [];
+  var set = {};
+  for (var i = 0; i < selection.length; i++) set[selection[i]] = true;
+  return items.filter(function(item) { return set[item[idKey]]; });
+}

package/src/dropdown/pages.jsx

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

package/src/dropdown/useDropdownController.js

@@ -0,0 +1,254 @@
+import { useState, useEffect, useMemo, useRef, useCallback } from 'react';
+import {
+  DROPDOWN_MODES,
+  normalizeKeys,
+  sortByKey,
+  filterByQuery,
+  pickSelected
+} from './dropdown.js';
+
+/**
+ * @param {object} props
+ * @param {'single'|'multi'} [props.mode='single']
+ * @param {Array} [props.options]                 — static items
+ * @param {() => Promise<Array>} [props.fetchData] — dynamic loader
+ * @param {Array<string>} [props.keys]            — [idKey, nameKey, ...extraKeys]; default ['id','name']
+ * @param {*} [props.value]                       — controlled selection (id, or id[])
+ * @param {*} [props.defaultValue]                — uncontrolled initial selection
+ * @param {(value, items) => void} [props.onChange]
+ * @param {string} [props.placeholder='Select…']
+ * @param {boolean} [props.searchable=true]
+ * @param {boolean} [props.disabled]
+ * @param {(name:string) => Promise<*>} [props.onCreate] — create a new option from the typed
+ *   name via your API; return the created item (or its id) and it is auto-selected.
+ * @param {boolean} [props.allowCreate=true] — show the "add new" affordance when onCreate is set
+ * @param {string} [props.createLabel='Add'] — label prefix on the create row (e.g. 'Add company')
+ */
+export function useDropdownController(props) {
+  props = props || {};
+  var mode = props.mode || 'single';
+  if (DROPDOWN_MODES.indexOf(mode) === -1) {
+    throw new Error('[xeplr-ui-utils:Dropdown] Unknown mode: ' + mode + '. Expected one of ' + DROPDOWN_MODES.join(', '));
+  }
+
+  var keys = useMemo(function() { return normalizeKeys(props.keys); }, [props.keys]);
+  var source = props.fetchData ? 'dynamic' : 'static';
+  var searchable = props.searchable !== false;
+  var canCreate = !!props.onCreate && props.allowCreate !== false;
+
+  var [dynamicItems, setDynamicItems] = useState([]);
+  var [loading, setLoading] = useState(false);
+  var [error, setError] = useState('');
+  var [query, setQuery] = useState('');
+  var [isOpen, setIsOpen] = useState(false);
+  var [creating, setCreating] = useState(false);
+  var [createError, setCreateError] = useState('');
+
+  var isControlled = props.value !== undefined;
+  var initialSelection = useMemo(function() {
+    var v = isControlled ? props.value : props.defaultValue;
+    if (v === undefined || v === null) return [];
+    return Array.isArray(v) ? v.slice() : [v];
+  }, [isControlled, props.value, props.defaultValue]);
+
+  var [selection, setSelection] = useState(initialSelection);
+
+  useEffect(function() {
+    if (isControlled) {
+      var v = props.value;
+      setSelection(v === null || v === undefined ? [] : (Array.isArray(v) ? v.slice() : [v]));
+    }
+  }, [isControlled, props.value]);
+
+  // Static items are derived (no state — avoids re-render loops if caller
+  // passes a new `options` array reference each render). Dynamic items come
+  // from the fetch effect below.
+  var items = useMemo(function() {
+    if (source === 'static') return sortByKey(props.options || [], keys.name);
+    return dynamicItems;
+  }, [source, props.options, dynamicItems, keys.name]);
+
+  // Load dynamic data on mount.
+  var fetchedRef = useRef(false);
+  useEffect(function() {
+    if (source !== 'dynamic' || fetchedRef.current) return;
+    fetchedRef.current = true;
+    setLoading(true);
+    setError('');
+    Promise.resolve()
+      .then(function() { return props.fetchData(); })
+      .then(function(data) {
+        setDynamicItems(sortByKey(Array.isArray(data) ? data : [], keys.name));
+      })
+      .catch(function(err) {
+        setError(err && err.message ? err.message : 'Failed to load options');
+      })
+      .finally(function() {
+        setLoading(false);
+      });
+  }, [source]);
+
+  function refresh() {
+    if (source !== 'dynamic') return;
+    setLoading(true);
+    setError('');
+    Promise.resolve()
+      .then(function() { return props.fetchData(); })
+      .then(function(data) {
+        setDynamicItems(sortByKey(Array.isArray(data) ? data : [], keys.name));
+      })
+      .catch(function(err) {
+        setError(err && err.message ? err.message : 'Failed to load options');
+      })
+      .finally(function() {
+        setLoading(false);
+      });
+  }
+
+  var searchKeys = useMemo(function() {
+    return [keys.name].concat(keys.extras);
+  }, [keys]);
+
+  var filteredItems = useMemo(function() {
+    return filterByQuery(items, query, searchKeys);
+  }, [items, query, searchKeys]);
+
+  var selectedItems = useMemo(function() {
+    return pickSelected(items, selection, keys.id);
+  }, [items, selection, keys.id]);
+
+  function open() { if (!props.disabled) setIsOpen(true); }
+  function close() { setIsOpen(false); setQuery(''); }
+  function toggle() { isOpen ? close() : open(); }
+
+  function emit(nextSelection, itemsOverride) {
+    var nextItems = pickSelected(itemsOverride || items, nextSelection, keys.id);
+    if (props.onChange) {
+      props.onChange(mode === 'single' ? (nextSelection[0] || null) : nextSelection, nextItems);
+    }
+  }
+
+  // Create a new option from the typed name via props.onCreate, then reload the
+  // (dynamic) options so the new row carries its real server id, and select it.
+  function createItem(rawName) {
+    var name = String(rawName != null ? rawName : query).trim();
+    if (!name || !props.onCreate) return Promise.resolve();
+    setCreating(true);
+    setCreateError('');
+    return Promise.resolve()
+      .then(function() { return props.onCreate(name); })
+      .then(function(created) {
+        if (source === 'dynamic' && props.fetchData) {
+          return Promise.resolve(props.fetchData()).then(function(data) {
+            var fresh = sortByKey(Array.isArray(data) ? data : [], keys.name);
+            setDynamicItems(fresh);
+            return { created: created, fresh: fresh };
+          });
+        }
+        return { created: created, fresh: items };
+      })
+      .then(function(ctx) {
+        var created = ctx.created;
+        var fresh = ctx.fresh;
+        var newId = null;
+        if (created && typeof created === 'object') newId = created[keys.id];
+        else if (created !== undefined && created !== null) newId = created;
+        if (newId == null) {
+          var match = fresh.filter(function(it) { return it[keys.name] === name; })[0];
+          if (match) newId = match[keys.id];
+        }
+        if (newId == null) return;   // created, but couldn't resolve an id — leave unselected
+        var next = mode === 'single'
+          ? [newId]
+          : (selection.indexOf(newId) === -1 ? selection.concat(newId) : selection);
+        if (!isControlled) setSelection(next);
+        emit(next, fresh);
+        if (mode === 'single') close();
+      })
+      .catch(function(err) {
+        setCreateError(err && err.message ? err.message : 'Failed to add');
+      })
+      .finally(function() {
+        setCreating(false);
+      });
+  }
+
+  function selectItem(itemId) {
+    var next;
+    if (mode === 'single') {
+      next = [itemId];
+      if (!isControlled) setSelection(next);
+      emit(next);
+      close();
+      return;
+    }
+    var has = selection.indexOf(itemId) !== -1;
+    next = has ? selection.filter(function(id) { return id !== itemId; }) : selection.concat(itemId);
+    if (!isControlled) setSelection(next);
+    emit(next);
+  }
+
+  function removeSelection(itemId) {
+    var next = selection.filter(function(id) { return id !== itemId; });
+    if (!isControlled) setSelection(next);
+    emit(next);
+  }
+
+  function clearSelection() {
+    if (!isControlled) setSelection([]);
+    emit([]);
+  }
+
+  function handleSearch(e) {
+    setQuery(e.target.value);
+  }
+
+  // Click-outside support — design wires this onto its container ref.
+  var rootRef = useRef(null);
+  useEffect(function() {
+    if (!isOpen) return;
+    function onDocClick(e) {
+      if (rootRef.current && !rootRef.current.contains(e.target)) {
+        close();
+      }
+    }
+    document.addEventListener('mousedown', onDocClick);
+    return function() { document.removeEventListener('mousedown', onDocClick); };
+  }, [isOpen]);
+
+  var isSelected = useCallback(function(itemId) {
+    return selection.indexOf(itemId) !== -1;
+  }, [selection]);
+
+  return {
+    mode,
+    source,
+    keys,
+    searchable,
+    canCreate,
+    createLabel: props.createLabel || 'Add',
+    creating,
+    createError,
+    createItem,
+    placeholder: props.placeholder || 'Select…',
+    disabled: !!props.disabled,
+    items,
+    filteredItems,
+    selectedItems,
+    selection,
+    loading,
+    error,
+    query,
+    isOpen,
+    rootRef,
+    isSelected,
+    open,
+    close,
+    toggle,
+    selectItem,
+    removeSelection,
+    clearSelection,
+    handleSearch,
+    refresh
+  };
+}

package/src/dropdown/validateDesign.js

@@ -0,0 +1,4 @@
+export var DROPDOWN_RULES = [
+  { selector: '.xeplr-dropdown-trigger, [role="combobox"]', label: 'Trigger element (combobox)' },
+  { selector: '.xeplr-dropdown-panel, [role="listbox"]', label: 'Options panel (listbox)' }
+];

package/src/gridDisplayer/designs/GridDisplayerSample.jsx

@@ -0,0 +1,58 @@
+import './gridDisplayer.css';
+
+export default function GridDisplayerSample({
+  query, setQuery,
+  sortFields, sortValue, setSortValue,
+  displayRows, tileFormatComponent, onSelect, onAddNew
+}) {
+  var TileFormatComponent = tileFormatComponent;
+
+  return (
+    <div className="xeplr-grid-displayer">
+      <div className="xeplr-grid-toolbar">
+        <input
+          type="text"
+          className="xeplr-grid-search"
+          placeholder="Search…"
+          value={query}
+          onChange={function(e) { setQuery(e.target.value); }}
+        />
+        {sortFields.length > 0 && (
+          <select
+            className="xeplr-grid-sort-select"
+            value={sortValue || ''}
+            onChange={function(e) { setSortValue(e.target.value || null); }}
+          >
+            {sortFields.map(function(f) {
+              return <option key={f.value} value={f.value}>{f.label}</option>;
+            })}
+          </select>
+        )}
+      </div>
+
+      <div className="xeplr-grid">
+        {onAddNew && (
+          <div className="xeplr-grid-tile xeplr-grid-tile-add" onClick={onAddNew}>
+            <TileFormatComponent isAddTile />
+          </div>
+        )}
+
+        {displayRows.map(function(row) {
+          return (
+            <div
+              key={row.id}
+              className="xeplr-grid-tile"
+              onClick={onSelect ? function() { onSelect(row); } : undefined}
+            >
+              <TileFormatComponent row={row} />
+            </div>
+          );
+        })}
+
+        {displayRows.length === 0 && !onAddNew && (
+          <div className="xeplr-grid-empty">No matches</div>
+        )}
+      </div>
+    </div>
+  );
+}

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