@xeplr/ui-utils 1.0.8 → 1.0.10

package/README.md

@@ -100,8 +100,12 @@ export default function SelectCompany() {
 | `DataImportPage` | [see below](#dataimportpage) | Upload a file, map its parts to targets, commit |
 | `ImportHistoryPage` | [see below](#importhistorypage) | Past imports in a `XeplrTable`, with Rollback and Delete |
 | `GridDisplayerPage` | [see below](#griddisplayerpage) | Searchable, sortable grid of tiles you render |
+| `ColorPickerPage` | [see below](#colorpickerpage) | Swatches, no colour, a custom colour, opacity and a live preview, as one CSS colour |
+| `ExpandersPage` | [see below](#panel-panelsection-panelfield-expanderspage) | Titled parts of a panel, one open at a time |
+| `SettingsTreePage` | [see below](#panel-panelsection-panelfield-expanderspage) | Nested groups of settings: cards, branches on a rail, one open per level |
+| `PanelSection`, `PanelField` | [see below](#panel-panelsection-panelfield-expanderspage) | A section card with an icon; a row with the label left and help under the control |
 | `ProgressNotifier` | [see below](#progressnotifier) | Indeterminate bar and a line of text for one event key |
-| `FileUploadSample`, `DataImportSample`, `ImportHistorySample`, `NumberFieldSample`, `DateFieldSample`, `DateRangeSample`, `RangeFieldSample`, `DropdownSample`, `GridDisplayerSample`, `TextFieldSample` | the matching controller's return value | The default designs, usable on their own |
+| `FileUploadSample`, `DataImportSample`, `ImportHistorySample`, `NumberFieldSample`, `DateFieldSample`, `DateRangeSample`, `RangeFieldSample`, `DropdownSample`, `GridDisplayerSample`, `TextFieldSample`, `ColorPickerSample`, `ExpandersSample`, `SettingsTreeSample` | the matching controller's return value | The default designs, usable on their own |
 
 ### Controllers (hooks)
 
@@ -114,9 +118,12 @@ export default function SelectCompany() {
 | `useNumberFieldController(props)` | NumberFieldPage props | `type, raw, numeric, error, placeholder, disabled, decimals, formatDisplay, affix {list, selected, position, labelKey, valueKey} \| null, handleNumberChange, handleAffixChange, handleBlur` |
 | `useTextFieldController(props)` | TextFieldPage props | `type, raw, error, remaining, placeholder, disabled, required, maxLength, rows, label, help, handleChange, handleBlur, handleKeyDown, handleClear` |
 | `useFileUploadController(options)` | FileUploadPage props | `files, uploading, progress, error, result, dragOver, inputRef, handleChange, handleDragOver, handleDragLeave, handleDrop, handleUpload, openFilePicker, removeFile(i), clear, allowedTypes, maxSize, maxFiles` |
-| `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), handleCommit, reset, accept, targetLabel` |
+| `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), setFix(i, key, on), checksOf(part), handleCommit, reset, accept, targetLabel` |
 | `useImportHistoryController(options)` | ImportHistoryPage props | `jobs, loading, error, rollingBackId, deletingId, reload, handleRollback(job), handleDelete(job)` |
 | `useGridDisplayerController(props)` | GridDisplayerPage props | `query, setQuery, sortFields, sortValue, setSortValue, displayRows, tileFormatComponent, onSelect, onAddNew` |
+| `useColorPickerController(props)` | ColorPickerPage props | `label, value, hex, opacity, swatches [{color, selected}], custom, allowNone, allowOpacity, previewText, pick(hex), setOpacity(0–100), clear` |
+| `useExpandersController(props)` | ExpandersPage props | `items` (each with `open`), `toggle(key)` |
+| `useSettingsTreeController(props)` | SettingsTreePage props | `nodes` (each with `open`, `depth`, `parentKey`, `children`), `toggle(parentKey, key)` |
 | `useDesignValidator(name, rules)` | page name, rule list | a ref for the design's container |
 
 ### Model functions (no React)
@@ -135,8 +142,11 @@ export default function SelectCompany() {
 | `NUMBER_TYPES`, `sanitizeNumberInput`, `toNumeric`, `formatDisplay`, `validateRange`, `resolveAffixState` | `['float','currency','units']`, `(raw)`, `(raw) → number \| null`, `(value, decimals?)`, `(value, min, max) → { valid, error? }`, `(type, options)` | Number field helpers. `sanitizeNumberInput` keeps digits, the first `.`, and a leading `-`. |
 | `TEXT_TYPES`, `toValue`, `normalise`, `validate`, `remaining` | `['text','multiline','search']`, `(raw) → string`, `(raw, { trim, maxLength })`, `(raw, { required, requiredMessage, minLength, maxLength, pattern, patternMessage }) → string \| null`, `(raw, maxLength) → number \| null` | Text field helpers |
 | `DROPDOWN_MODES`, `normalizeKeys`, `sortByKey`, `filterByQuery`, `pickSelected` | `['single','multi']`, `(keys) → { id, name, extras }`, `(items, key)`, `(items, query, searchKeys)`, `(items, ids, idKey)` | Dropdown helpers |
+| `DEFAULT_SWATCHES`, `parseColor`, `formatColor`, `sameHue` | `[hex]`, `(css) → { hex, opacity } \| null`, `(hex, opacity) → css \| null`, `(a, b) → boolean` | Colour helpers. Opacity 100 writes `#RRGGBB`; anything less writes `#RRGGBBAA`. |
+| `toggleOpen`, `initialOpen` | `(open, key, multiple?) → keys`, `(items, initial?, multiple?) → keys` | Which expanders are open |
+| `toggleBranch`, `decorateTree` | `(open, parentKey, key) → open`, `(nodes, open) → nodes` | Which branch of a settings tree is open at each level; `open` is `{ [parentKey]: key }`, the root's parent `''` |
 | `filterGridRows`, `sortGridRows` | `(rows, query, fields)`, `(rows, field, 'asc'\|'desc')` | Grid search and sort. An array field matches if any entry matches. |
-| `sanitizeTargetName`, `buildInitialMappings` | `(name) → string`, `({ parts?, originalName? }) → [{ part, target, include }]` | Data import mapping |
+| `sanitizeTargetName`, `buildInitialMappings`, `checksFor` | `(name) → string`, `({ parts?, originalName?, checks? }) → [{ part, target, include, fixes }]`, `(inspectResult, part) → checks[]` | Data import mapping |
 | `configureUpload`, `uploadFile` | `({ url, headers, getHeaders })`, `(files, { url, fieldName, extraData, onProgress }) → Promise` | Multipart upload over XHR |
 | `attachProgressSource`, `progressSourceAttached`, `subscribeToProgress`, `describeProgress`, `describeComplete` | `(subscribe)`, `() → boolean`, `(key, handler) → unsubscribe`, `(data, noun?)`, `(data, noun?)` | The progress event source and its sentences |
 
@@ -155,7 +165,7 @@ export default function SelectCompany() {
 | `deepMerge` | `(base, override)` | Immutable merge. Arrays are replaced, and `undefined` never overwrites a value. |
 | `COUNTRIES` | `[{ code, name }]` | 196 countries |
 | `STATES`, `STATES_IN` | `{ IN: [{ code, name }] }`, `[{ code, name }]` | 36 Indian states and union territories |
-| `FILE_UPLOAD_RULES`, `DATA_IMPORT_RULES`, `IMPORT_HISTORY_RULES`, `NUMBER_FIELD_RULES`, `DATE_FIELD_RULES`, `DATE_RANGE_RULES`, `RANGE_FIELD_RULES`, `DROPDOWN_RULES`, `GRID_DISPLAYER_RULES`, `TEXT_FIELD_RULES` | rule arrays | What each page requires of a design |
+| `FILE_UPLOAD_RULES`, `DATA_IMPORT_RULES`, `IMPORT_HISTORY_RULES`, `NUMBER_FIELD_RULES`, `DATE_FIELD_RULES`, `DATE_RANGE_RULES`, `RANGE_FIELD_RULES`, `DROPDOWN_RULES`, `GRID_DISPLAYER_RULES`, `TEXT_FIELD_RULES`, `COLOR_PICKER_RULES`, `EXPANDERS_RULES`, `SETTINGS_TREE_RULES` | rule arrays | What each page requires of a design |
 
 ## DropdownPage
 
@@ -284,13 +294,15 @@ configureUpload({ url: '/uploads', getHeaders: () => ({ Authorization: 'Bearer '
 
 | prop | type | meaning |
 |---|---|---|
-| `onInspect` | `(filePath, file) => Promise<{ format, parts? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. |
-| `onCommit` | `(filePath, [{ part, target }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. |
+| `onInspect` | `(filePath, file) => Promise<{ format, parts?, checks? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. `checks` says what is wrong with a part before it is loaded — see below. |
+| `onCommit` | `(filePath, [{ part, target, fixes }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. `fixes` is the person's choice for each fix the checks offered. |
 | `accept` | `string` | The file input's `accept` attribute, for example `'.csv,.json,.xlsx,.xls'` |
 | `targetLabel` | `string` | Placeholder for the target name (default `'Target'`) |
 
 The file is sent through this package's own `uploadFile()` to the URL set by `configureUpload`, not through a prop. That keeps the component free of app-specific upload wiring. The apps point it at `@xeplr/base-apis`' generic upload route. The upload response must include `filePath`. With `parts`, each part becomes a row (included by default) whose target is `sanitizeTargetName(part)`. Without `parts`, there is one row named after the file. Result rows show `target (part)` and then `rows` + " rows", "Done", or `error`, depending on `success`.
 
+**Checks, before anything is loaded.** `onInspect` may return `checks: { [part]: [{ key, message, fixLabel?, fixDefault?, examples? }] }` (the key `''` for a one-unit file). Each shows under its part as a warning with its message and examples. One with a `fixLabel` offers the fix as a checkbox, on unless `fixDefault: false`; the choice reaches `onCommit` as `fixes[key]`. A result row's `note` is shown under it — what a fix did. The component knows no particular check: the app decides what to look for and what its fix means (BI: rows pasted into one cell, recovered).
+
 `sanitizeTargetName('Sales 2024.xlsx')` returns `'sales_2024'`. It lowercases, drops the extension, turns runs of non-`[a-z0-9_]` characters into `_`, trims `_` from both ends, and falls back to `'table'`.
 
 ## ImportHistoryPage
@@ -325,6 +337,52 @@ function Tile({ row, isAddTile }) {
 | `onSelect` | `(row) => void` | — | Tile click |
 | `onAddNew` | `() => void` | — | If given, a leading add tile is shown |
 
+## ColorPickerPage
+
+```jsx
+<ColorPickerPage label="Background" value={fill} onChange={setFill} />
+```
+
+| prop | default | meaning |
+|---|---|---|
+| `value` | — | `'#RRGGBB'`, `'#RRGGBBAA'`, or `null` for no colour |
+| `onChange` | — | `(value \| null) => void`, on every pick, slide or clear |
+| `swatches` | `DEFAULT_SWATCHES` | 14 soft and strong colours |
+| `allowNone` | `true` | Offer "no colour" |
+| `allowOpacity` | `true` | The opacity slider and % box |
+| `previewText` | `'Aa 123'` | Text in the preview box |
+| `label` | — | Line above the swatches |
+
+**The value is one CSS colour, never a colour plus an opacity.** `#RRGGBBAA` is understood by every browser and style sheet, so a saved style needs no second field and nothing else has to learn about opacity. A colour not among the swatches still shows as picked, in the custom swatch.
+
+## Panel: PanelSection, PanelField, ExpandersPage
+
+The parts of a settings panel. `PanelSection` and `PanelField` are presentation only and take children; the expanders have a controller.
+
+```jsx
+<PanelSection icon={<TypeIcon />} title="Field" subtitle="What this column is">
+  <PanelField label="Label" help="Shown as the column header">
+    <input value={label} onChange={…} />
+  </PanelField>
+</PanelSection>
+
+<ExpandersPage items={[
+  { key: 'text', title: 'Text', summary: 'Inter · 13px', icon: <T />, content: <TextRows /> },
+  { key: 'fill', title: 'Fill', content: <ColorPickerPage … /> }
+]} />
+```
+
+| component | props |
+|---|---|
+| `PanelSection` | `icon`, `title`, `subtitle`, `actions` (right of the title), `className`, children |
+| `PanelField` | `label`, `badge`, `help` (under the control), `htmlFor`, `stacked` (control under the label, for wide controls), children |
+| `SettingsTreePage` | `nodes: [{ key, title, icon?, count?, content?, children? }]`, `initial` (`{ [parentKey]: key }`, root parent `''`) |
+| `ExpandersPage` | `items: [{ key, title, summary?, icon?, content }]`, `initial` (key or keys open at first; default the first item; `null` for none), `multiple` (let several be open) |
+
+Opening an expander closes the others unless `multiple`: a long panel with every part open is the scroll the expanders exist to avoid.
+
+`SettingsTreePage` is for a panel with more settings than expanders can hold — a chart has over a hundred, four levels deep. Top-level nodes are cards (an icon tile, the title, `count` as a badge, a chevron); an open one is tinted with an accent bar and lists its children as rows on a dotted rail. A node shows its own `content` first, then its children. One branch is open per level, for the same reason as the expanders. Give every top-level node an icon or none of them: a panel where some groups have one reads as unfinished.
+
 ## ProgressNotifier
 
 Attach your app's event stream **once** at startup, then mount notifiers anywhere with a key. From `xeplr-bi`:
@@ -395,17 +453,21 @@ These create their own DOM nodes with inline styles, so they need no provider, m
 | `FILE_UPLOAD_RULES` | `input[type="file"]`; `.xeplr-upload-dropzone` or `[role="dropzone"]`; a `button` |
 | `DATA_IMPORT_RULES` | `input[type="file"]` |
 | `GRID_DISPLAYER_RULES` | `.xeplr-grid-search`; `.xeplr-grid` |
+| `COLOR_PICKER_RULES` | `.xeplr-colorpicker-swatch` or `[role="option"]` |
+| `EXPANDERS_RULES` | `.xeplr-expander-head` or `[aria-expanded]` |
+| `SETTINGS_TREE_RULES` | `.xeplr-tree-head` or `[aria-expanded]` |
 | `IMPORT_HISTORY_RULES` | nothing |
 
 ## Theming
 
-The designs use `xeplr-*` class prefixes (`xeplr-dropdown-*`, `xeplr-daterange-*`, `xeplr-rangefield-*`, `xeplr-datefield-*`, `xeplr-numberfield-*`, `xeplr-textfield-*`, `xeplr-upload-*`, `xeplr-data-import-*`, `xeplr-import-history-*`, `xeplr-grid-*`). The progress notifier uses `xpn`, `xpn--running` / `--complete` / `--error`, `xpn-bar` and `xpn-text`. What each design reads:
+The designs use `xeplr-*` class prefixes (`xeplr-dropdown-*`, `xeplr-daterange-*`, `xeplr-rangefield-*`, `xeplr-datefield-*`, `xeplr-numberfield-*`, `xeplr-textfield-*`, `xeplr-upload-*`, `xeplr-data-import-*`, `xeplr-import-history-*`, `xeplr-grid-*`, `xeplr-colorpicker-*`, `xeplr-panel-*`, `xeplr-expander-*`, `xeplr-tree-*`). The progress notifier uses `xpn`, `xpn--running` / `--complete` / `--error`, `xpn-bar` and `xpn-text`. What each design reads:
 
 | design | reads | without it |
 |---|---|---|
 | Dropdown, DataImport, ImportHistory, GridDisplayer | `@xeplr/ui-account` theme tokens: `--xeplr-bg-*`, `--xeplr-text-*`, `--xeplr-border-*`, `--xeplr-input-bg/-border/-text/-placeholder`, `--xeplr-accent`, `--xeplr-accent-text`, `--xeplr-danger*`, `--xeplr-success`, `--xeplr-tag-*`, `--xeplr-shadow-lg` | dark fallbacks |
 | Snackbar, confirm dialogs | `--xeplr-success`, `--xeplr-danger`, `--xeplr-accent`, `--xeplr-accent-text`, `--xeplr-bg-overlay`, `--xeplr-bg-secondary/-tertiary`, `--xeplr-text-primary/-secondary`, `--xeplr-border-primary`, `--xeplr-shadow-lg` | the snackbar's original colours; a dark dialog |
 | DateRange, RangeField, ProgressNotifier | `--xeplr-surface`, `--xeplr-surface-2`, `--xeplr-border`, `--xeplr-border-strong`, `--xeplr-border-secondary`, `--xeplr-muted`, `--xeplr-muted-2`, `--xeplr-text`, `--xeplr-hover`, `--xeplr-accent`, `--xeplr-danger`, `--xeplr-success` | light fallbacks. Of these, `ui-account`'s `theme.css` defines only accent, danger, success and border-secondary. |
+| ColorPicker, Panel | `--xeplr-bg-primary`, `--xeplr-bg-secondary`, `--xeplr-border-primary`, `--xeplr-border-focus`, `--xeplr-text-primary/-secondary/-muted`, `--xeplr-accent`, `--xeplr-accent-soft` | light fallbacks |
 | TextField | `--xeplr-input-text-*` (gap, padding, bg, colour, font size, placeholder, each border edge, border colour/hover/focus, radius, the full label font, help text, focus ring, invalid) | shipped defaults |
 | NumberField, DateField (and so RangeField's two inputs), FileUpload | fixed dark colours, no variables | — |
 
@@ -444,7 +506,7 @@ An edge set to `false` becomes `0` instead of being left out, because a missing
 src/
   index.js                ─ everything below
   <control>/              ─ dropdown, dateRange, rangeField, dateField, numberField, textField,
-                            fileUpload, dataImport, gridDisplayer — each has:
+                            fileUpload, dataImport, gridDisplayer, colorPicker, panel — each has:
     <control>.js            model (pure; dataImport.js, uploadFile.js)
     use*Controller.js       controller
     validateDesign.js       *_RULES (fileUpload's also defines useDesignValidator)
@@ -455,7 +517,8 @@ src/
   confirm/confirm.js      ─ raiseConfirm, raiseChoice
   theme/                  ─ default.theme.json, index.js (resolveTheme, getThemeVariant, getChartOptions, inputStyleVars, deepMerge)
   data/                   ─ countries.json, states.json
-test/                     ─ dateRange, rangeField, textField (+ inputStyleVars), validateDesign (DATE_RANGE_RULES)
+test/                     ─ dateRange, rangeField, textField (+ inputStyleVars), colorPicker, panel,
+                            validateDesign (DATE_RANGE_RULES), designRules (COLOR_PICKER_RULES, EXPANDERS_RULES, SETTINGS_TREE_RULES)
 ```
 
 ## Tests
@@ -464,7 +527,7 @@ test/                     ─ dateRange, rangeField, textField (+ inputStyleVars
 npm test
 ```
 
-This runs each `test/*.test.js` with plain `node` and stops at the first failing file. The tests cover the date range model, the range field model, the text field model with `inputStyleVars`, and the date range design rules. CI runs the same files with `node --test` and coverage.
+This runs each `test/*.test.js` with plain `node` and stops at the first failing file. The tests cover the date range model, the range field model, the text field model with `inputStyleVars`, the colour, expander and settings-tree models, and the design rules of the date range, colour picker, expanders and settings tree. CI runs the same files with `node --test` and coverage.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-utils",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "UI utility components: file upload with progress, snackbar, static data (countries/states)",
   "type": "module",
   "main": "src/index.js",

package/src/colorPicker/colorPicker.js

@@ -0,0 +1,39 @@
+// ColorPicker — model. A colour and how see-through it is, kept as ONE CSS
+// value: '#RRGGBB' when solid, '#RRGGBBAA' when not — a string every browser,
+// every style sheet and every saved style already understands. No React here.
+
+/** Soft swatches that read well behind text, light and dark. */
+export var DEFAULT_SWATCHES = [
+  '#f3f4f6', '#dbe8ff', '#d9f2e3', '#fdecc8', '#fde0d4', '#f8dcf0', '#e6defd',
+  '#9ca3af', '#4f7cff', '#22a06b', '#e0a106', '#e5673d', '#d14fa8', '#7c5cff'
+];
+
+var HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * '#abc', '#aabbcc' or '#aabbccdd' → { hex: '#aabbcc', opacity: 0–100 }, or
+ * null for anything else (no colour).
+ */
+export function parseColor(value) {
+  var m = HEX.exec(String(value || '').trim());
+  if (!m) return null;
+  var h = m[1].toLowerCase();
+  if (h.length === 3) h = h.split('').map(function(c) { return c + c; }).join('');
+  var alpha = h.length === 8 ? parseInt(h.slice(6), 16) : 255;
+  return { hex: '#' + h.slice(0, 6), opacity: Math.round(alpha / 255 * 100) };
+}
+
+/** { hex, opacity } → the one CSS value: '#RRGGBB' when opacity is 100, '#RRGGBBAA' otherwise. */
+export function formatColor(hex, opacity) {
+  var parsed = parseColor(hex);
+  if (!parsed) return null;
+  var o = Math.max(0, Math.min(100, Math.round(Number(opacity))));
+  if (isNaN(o) || o === 100) return parsed.hex;
+  return parsed.hex + Math.round(o / 100 * 255).toString(16).padStart(2, '0');
+}
+
+/** Whether two colours are the same swatch, whatever their opacity. */
+export function sameHue(a, b) {
+  var pa = parseColor(a), pb = parseColor(b);
+  return Boolean(pa && pb && pa.hex === pb.hex);
+}

package/src/colorPicker/designs/ColorPickerSample.jsx

@@ -0,0 +1,56 @@
+import './colorPicker.css';
+
+/**
+ * ColorPicker — design. Presentation only; everything from
+ * useColorPickerController. Swatches, "no colour", a custom colour, opacity
+ * as a slider and a number, and a live preview of the result.
+ */
+export default function ColorPickerSample(props) {
+  return (
+    <div className="xeplr-colorpicker-wrap">
+      <div className="xeplr-colorpicker">
+        <div className="xeplr-colorpicker-main">
+          {props.label && <div className="xeplr-colorpicker-label">{props.label}</div>}
+          <div className="xeplr-colorpicker-swatches" role="listbox" aria-label={props.label || 'Colour'}>
+            {props.allowNone && (
+              <button type="button" role="option" aria-selected={!props.value} title="No colour"
+                className={'xeplr-colorpicker-swatch xeplr-colorpicker-none' + (!props.value ? ' selected' : '')}
+                onClick={props.clear}>
+                <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><circle cx="8" cy="8" r="6" fill="none" stroke="currentColor" strokeWidth="1.5" /><path d="M4 12 12 4" stroke="currentColor" strokeWidth="1.5" /></svg>
+              </button>
+            )}
+            {props.swatches.map(function(s) {
+              return (
+                <button key={s.color} type="button" role="option" aria-selected={s.selected} title={s.color}
+                  className={'xeplr-colorpicker-swatch' + (s.selected ? ' selected' : '')}
+                  style={{ background: s.color }} onClick={function() { props.pick(s.color); }} />
+              );
+            })}
+            <label className={'xeplr-colorpicker-swatch xeplr-colorpicker-custom' + (props.custom ? ' selected' : '')}
+              title="Another colour" style={props.custom ? { background: props.hex } : undefined}>
+              {!props.custom && <span aria-hidden="true">+</span>}
+              <input type="color" value={props.hex || '#4f7cff'} onChange={function(e) { props.pick(e.target.value); }} aria-label="Another colour" />
+            </label>
+          </div>
+          {props.allowOpacity && (
+            <div className="xeplr-colorpicker-opacity">
+              <span className="xeplr-colorpicker-label">Opacity</span>
+              <div className="xeplr-colorpicker-opacity-row">
+                <input type="range" min="0" max="100" value={props.opacity} disabled={!props.value}
+                  onChange={function(e) { props.setOpacity(Number(e.target.value)); }} aria-label="Opacity" />
+                <span className="xeplr-colorpicker-opacity-value">
+                  <input type="number" min="0" max="100" value={props.opacity} disabled={!props.value}
+                    onChange={function(e) { props.setOpacity(Number(e.target.value)); }} aria-label="Opacity percent" />%
+                </span>
+              </div>
+            </div>
+          )}
+        </div>
+        <div className="xeplr-colorpicker-preview">
+          <span className="xeplr-colorpicker-label">Preview</span>
+          <div className="xeplr-colorpicker-preview-box" style={props.value ? { background: props.value } : undefined}>{props.previewText}</div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/colorPicker/designs/colorPicker.css

@@ -0,0 +1,36 @@
+/* Measured against its own width, not the window's: a picker in a narrow
+   side panel puts its preview under the swatches instead of beside them. */
+.xeplr-colorpicker-wrap { container-type: inline-size; }
+.xeplr-colorpicker { display: flex; gap: 16px; align-items: stretch; }
+.xeplr-colorpicker-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 10px; }
+.xeplr-colorpicker-label { font-size: 11.5px; color: var(--xeplr-text-muted, #6b7280); }
+.xeplr-colorpicker-swatches { display: flex; flex-wrap: wrap; gap: 8px; }
+.xeplr-colorpicker-swatch {
+  position: relative; width: 28px; height: 28px; border-radius: 8px; padding: 0; cursor: pointer;
+  border: 1px solid var(--xeplr-border-primary, #e2e5eb); background: var(--xeplr-bg-primary, #fff);
+  display: inline-flex; align-items: center; justify-content: center; color: var(--xeplr-text-muted, #6b7280);
+  transition: transform .1s, box-shadow .12s;
+}
+.xeplr-colorpicker-swatch:hover { transform: translateY(-1px); }
+.xeplr-colorpicker-swatch.selected { box-shadow: 0 0 0 2px var(--xeplr-bg-primary, #fff), 0 0 0 4px var(--xeplr-accent, #4f5fd6); }
+.xeplr-colorpicker-custom input[type="color"] { position: absolute; inset: 0; opacity: 0; cursor: pointer; width: 100%; height: 100%; border: 0; padding: 0; }
+.xeplr-colorpicker-opacity { display: flex; flex-direction: column; gap: 6px; }
+.xeplr-colorpicker-opacity-row { display: flex; align-items: center; gap: 10px; }
+.xeplr-colorpicker-opacity-row input[type="range"] { flex: 1; accent-color: var(--xeplr-accent, #4f5fd6); }
+.xeplr-colorpicker-opacity-value {
+  display: inline-flex; align-items: center; gap: 2px; font-size: 12.5px; padding: 6px 10px;
+  border: 1px solid var(--xeplr-border-primary, #e2e5eb); border-radius: 8px; background: var(--xeplr-bg-primary, #fff);
+}
+.xeplr-colorpicker-opacity-value input { width: 32px; -moz-appearance: textfield; appearance: textfield; border: 0; background: transparent; text-align: right; font: inherit; color: inherit; padding: 0; }
+.xeplr-colorpicker-preview { width: 120px; flex-shrink: 0; display: flex; flex-direction: column; gap: 6px; padding-left: 16px; border-left: 1px solid var(--xeplr-border-primary, #e2e5eb); }
+.xeplr-colorpicker-preview-box {
+  flex: 1; min-height: 44px; display: flex; align-items: center; padding: 0 12px; border-radius: 10px;
+  border: 1px solid var(--xeplr-border-primary, #e2e5eb); font-size: 14px; font-weight: 600; color: var(--xeplr-text-primary, #1f2937);
+}
+
+@container (max-width: 340px) {
+  .xeplr-colorpicker { flex-direction: column; gap: 12px; }
+  .xeplr-colorpicker-preview { width: auto; padding-left: 0; border-left: 0; padding-top: 12px; border-top: 1px solid var(--xeplr-border-primary, #e2e5eb); }
+}
+.xeplr-colorpicker-opacity-value input::-webkit-inner-spin-button,
+.xeplr-colorpicker-opacity-value input::-webkit-outer-spin-button { -webkit-appearance: none; margin: 0; }

package/src/colorPicker/designs/index.js

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

package/src/colorPicker/pages.jsx

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

package/src/colorPicker/useColorPickerController.js

@@ -0,0 +1,41 @@
+import { DEFAULT_SWATCHES, parseColor, formatColor, sameHue } from './colorPicker.js';
+
+/**
+ * ColorPicker — controller. The value is one CSS colour (see colorPicker.js);
+ * every change goes straight to onChange. No JSX here.
+ *
+ * @param {object} props
+ * @param {string|null} props.value       - '#RRGGBB' / '#RRGGBBAA', or null for none
+ * @param {Function}    props.onChange    - (value|null) => void
+ * @param {string[]}    [props.swatches]  - default DEFAULT_SWATCHES
+ * @param {boolean}     [props.allowNone] - default true: offer "no colour"
+ * @param {boolean}     [props.allowOpacity] - default true
+ * @param {string}      [props.previewText] - default 'Aa 123'
+ * @param {string}      [props.label]
+ */
+export function useColorPickerController(props) {
+  var onChange = props.onChange || function() {};
+  var parsed = parseColor(props.value);
+  var swatches = props.swatches || DEFAULT_SWATCHES;
+  var opacity = parsed ? parsed.opacity : 100;
+
+  function pick(hex) { onChange(formatColor(hex, parsed ? opacity : 100)); }
+  function setOpacity(value) { if (parsed) onChange(formatColor(parsed.hex, value)); }
+  function clear() { onChange(null); }
+
+  return {
+    label: props.label || null,
+    value: parsed ? formatColor(parsed.hex, opacity) : null,
+    hex: parsed ? parsed.hex : null,
+    opacity: opacity,
+    swatches: swatches.map(function(s) { return { color: s, selected: sameHue(s, props.value) }; }),
+    // A colour not among the swatches still shows as picked, in the custom one.
+    custom: Boolean(parsed && !swatches.some(function(s) { return sameHue(s, props.value); })),
+    allowNone: props.allowNone !== false,
+    allowOpacity: props.allowOpacity !== false,
+    previewText: props.previewText || 'Aa 123',
+    pick: pick,
+    setOpacity: setOpacity,
+    clear: clear
+  };
+}

package/src/colorPicker/validateDesign.js

@@ -0,0 +1,4 @@
+// A colour picker design must offer swatches to pick from.
+export var COLOR_PICKER_RULES = [
+  { selector: '.xeplr-colorpicker-swatch, [role="option"]', label: 'Swatches to pick from' }
+];

package/src/dataImport/dataImport.js

@@ -16,8 +16,26 @@ export function sanitizeTargetName(name) {
     .replace(/^_+|_+$/g, '') || 'table';
 }
 
-// inspectResult: { filePath, format, originalName?, parts?: string[] }
-// -> [{ part: string|null, target: string, include: boolean }]
+// What the inspect step found wrong with one part, if anything:
+//   inspectResult.checks = { [part]: [{ key, message, fixLabel?, fixDefault? }] }
+// (the key '' for a file that is one unit). A check with a fixLabel offers a
+// fix the person switches on or off before importing; its choice travels
+// with the mapping as fixes[key].
+export function checksFor(inspectResult, part) {
+  var all = (inspectResult && inspectResult.checks) || {};
+  return all[part == null ? '' : part] || [];
+}
+
+function initialFixes(inspectResult, part) {
+  var fixes = {};
+  checksFor(inspectResult, part).forEach(function(c) {
+    if (c.fixLabel) fixes[c.key] = c.fixDefault !== false;
+  });
+  return fixes;
+}
+
+// inspectResult: { filePath, format, originalName?, parts?: string[], checks? }
+// -> [{ part: string|null, target: string, include: boolean, fixes: { [key]: boolean } }]
 //
 // parts present (e.g. Excel sheets) -> one row per part, all included by
 // default. parts absent (e.g. CSV/JSON — the whole file is one unit) -> a
@@ -25,8 +43,8 @@ export function sanitizeTargetName(name) {
 export function buildInitialMappings(inspectResult) {
   if (inspectResult.parts && inspectResult.parts.length) {
     return inspectResult.parts.map(function(part) {
-      return { part: part, target: sanitizeTargetName(part), include: true };
+      return { part: part, target: sanitizeTargetName(part), include: true, fixes: initialFixes(inspectResult, part) };
     });
   }
-  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true }];
+  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true, fixes: initialFixes(inspectResult, null) }];
 }

package/src/dataImport/designs/DataImportSample.jsx

@@ -2,7 +2,7 @@ import './dataImport.css';
 
 export default function DataImportSample({
   file, inspecting, inspected, mappings, committing, results, error,
-  handleFileChange, updateMapping, handleCommit, reset, accept, targetLabel
+  handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel
 }) {
   return (
     <div className="xeplr-data-import">
@@ -37,6 +37,31 @@ export default function DataImportSample({
                   onChange={function(e) { updateMapping(i, { target: e.target.value }); }}
                   placeholder={targetLabel}
                 />
+                {/* What the inspect step found, before anything is loaded —
+                    and the fix, when one is offered, as a choice. */}
+                {(checksOf ? checksOf(m.part) : []).map(function(c) {
+                  return (
+                    <div key={c.key} className="xeplr-data-import-check" role="alert">
+                      <p className="xeplr-data-import-check-message">{c.message}</p>
+                      {c.fixLabel && (
+                        <label className="xeplr-data-import-check-fix">
+                          <input
+                            type="checkbox"
+                            checked={Boolean(m.fixes && m.fixes[c.key])}
+                            disabled={!m.include}
+                            onChange={function(e) { setFix(i, c.key, e.target.checked); }}
+                          />
+                          {c.fixLabel}
+                        </label>
+                      )}
+                      {(c.examples || []).length > 0 && (
+                        <ul className="xeplr-data-import-check-examples">
+                          {c.examples.map(function(x, xi) { return <li key={xi}>{x}</li>; })}
+                        </ul>
+                      )}
+                    </div>
+                  );
+                })}
               </div>
             );
           })}
@@ -61,6 +86,7 @@ export default function DataImportSample({
                 <span className={r.success ? 'xeplr-data-import-result-ok' : 'xeplr-data-import-result-fail'}>
                   {r.success ? (r.rows != null ? r.rows + ' rows' : 'Done') : (r.error || 'Failed')}
                 </span>
+                {r.note && <span className="xeplr-data-import-result-note">{r.note}</span>}
               </div>
             );
           })}

package/src/dataImport/designs/dataImport.css

@@ -96,3 +96,22 @@
 .xeplr-import-history-status-failed { color: var(--xeplr-danger, #ff6b6b); }
 .xeplr-import-history-status-rolled-back { color: var(--xeplr-text-muted, #888); }
 .xeplr-import-history-error { color: var(--xeplr-text-secondary, #999); }
+
+/* What the inspect step found in a part — on its own line under the part,
+   with the fix (when one is offered) as a checkbox the person decides. */
+.xeplr-data-import-mapping-row { flex-wrap: wrap; }
+.xeplr-data-import-check {
+  flex-basis: 100%;
+  margin: 2px 0 4px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid var(--xeplr-warning, #a86a00);
+  background: var(--xeplr-warning-bg, rgba(168, 106, 0, 0.08));
+  color: var(--xeplr-text-primary, #e0e0e0);
+  font-size: 13px;
+}
+.xeplr-data-import-check-message { margin: 0 0 6px; line-height: 1.45; }
+.xeplr-data-import-check-fix { display: flex; align-items: center; gap: 8px; font-weight: 600; cursor: pointer; }
+.xeplr-data-import-check-examples { margin: 6px 0 0; padding-left: 18px; font-size: 12px; color: var(--xeplr-text-muted, #888); }
+.xeplr-data-import-result-note { flex-basis: 100%; font-size: 12px; color: var(--xeplr-text-muted, #888); }
+.xeplr-data-import-result-row { flex-wrap: wrap; }

package/src/dataImport/useDataImportController.js

@@ -1,16 +1,18 @@
 import { useState } from 'react';
 import { uploadFile } from '../fileUpload/uploadFile.js';
-import { buildInitialMappings } from './dataImport.js';
+import { buildInitialMappings, checksFor } from './dataImport.js';
 
 /**
  * @param {object} options
  * @param {string} [options.accept] - file input accept attribute, e.g. '.csv,.json,.xlsx,.xls'
  * @param {string} [options.targetLabel='Target'] - placeholder/label for the target-name field
- * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[]}>} options.onInspect
+ * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[], checks?: object}>} options.onInspect
  *   - required. App-supplied: given a file ALREADY uploaded (see below), what
  *     does it contain? (format, and for a multi-part file like an Excel
  *     workbook, its part/sheet names).
- * @param {(filePath: string, mappings: {part: string|null, target: string}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ * @param {(filePath: string, mappings: {part: string|null, target: string, fixes: object}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ *   (each mapping's `fixes` is the person's choice for each fix the inspect
+ *   step's `checks` offered — see checksFor in dataImport.js)
  *   - required. App-supplied: load the included parts into their targets.
  *     meta.originalName is the picked file's own name (not the server-side
  *     path) — pass it through if the app wants it recorded (e.g. import
@@ -61,6 +63,15 @@ export function useDataImportController(options = {}) {
     }
   }
 
+  // A fix the inspect step offered, switched on or off for one part.
+  function setFix(index, key, on) {
+    setMappings(function(prev) {
+      var next = prev.slice();
+      next[index] = Object.assign({}, next[index], { fixes: Object.assign({}, next[index].fixes, { [key]: on }) });
+      return next;
+    });
+  }
+
   function updateMapping(index, patch) {
     setMappings(function(prev) {
       var next = prev.slice();
@@ -75,7 +86,7 @@ export function useDataImportController(options = {}) {
     setCommitting(true);
     setError('');
     try {
-      var payload = included.map(function(m) { return { part: m.part, target: m.target }; });
+      var payload = included.map(function(m) { return { part: m.part, target: m.target, fixes: m.fixes || {} }; });
       var res = await options.onCommit(inspected.filePath, payload, { originalName: inspected.originalName });
       setResults((res && res.results) || res || []);
     } catch (err) {
@@ -87,7 +98,8 @@ export function useDataImportController(options = {}) {
 
   return {
     file, inspecting, inspected, mappings, committing, results, error,
-    handleFileChange, updateMapping, handleCommit, reset,
+    handleFileChange, updateMapping, setFix, handleCommit, reset,
+    checksOf: function(part) { return checksFor(inspected, part); },
     accept: options.accept,
     targetLabel: options.targetLabel || 'Target'
   };

package/src/index.js

@@ -198,3 +198,22 @@ export { TextFieldPage } from './textField/pages.jsx';
 export { attachProgressSource, progressSourceAttached, subscribeToProgress,
          describeProgress, describeComplete } from './progress/progressSource.js';
 export { default as ProgressNotifier } from './progress/ProgressNotifier.jsx';
+
+// ColorPicker — one CSS colour, '#RRGGBB' solid or '#RRGGBBAA' see-through:
+// swatches, "no colour", a custom colour, opacity, and a live preview.
+export { DEFAULT_SWATCHES, parseColor, formatColor, sameHue } from './colorPicker/colorPicker.js';
+export { useColorPickerController } from './colorPicker/useColorPickerController.js';
+export { COLOR_PICKER_RULES } from './colorPicker/validateDesign.js';
+export { ColorPickerSample } from './colorPicker/designs/index.js';
+export { ColorPickerPage } from './colorPicker/pages.jsx';
+
+// Panel — the parts of a settings panel: section cards (PanelSection), rows
+// with the label left and help under the control (PanelField), and
+// expanders, opened one at a time unless `multiple`; and a settings tree —
+// groups as cards, branches on a rail, one open per level.
+export { toggleOpen, initialOpen, toggleBranch, decorateTree } from './panel/panel.js';
+export { useExpandersController } from './panel/useExpandersController.js';
+export { useSettingsTreeController } from './panel/useSettingsTreeController.js';
+export { EXPANDERS_RULES, SETTINGS_TREE_RULES } from './panel/validateDesign.js';
+export { PanelSection, PanelField, ExpandersSample, SettingsTreeSample } from './panel/designs/index.js';
+export { ExpandersPage, SettingsTreePage } from './panel/pages.jsx';

package/src/panel/designs/ExpandersSample.jsx

@@ -0,0 +1,29 @@
+import './panel.css';
+
+/**
+ * Expanders — design. Each item a header (icon, title, a short summary of
+ * what is set) that opens its content. Everything from useExpandersController.
+ */
+export default function ExpandersSample(props) {
+  return (
+    <div className="xeplr-expanders">
+      {props.items.map(function(item) {
+        var id = 'xeplr-expander-' + item.key;
+        return (
+          <div key={item.key} className={'xeplr-expander' + (item.open ? ' open' : '')}>
+            <button type="button" className="xeplr-expander-head" aria-expanded={item.open} aria-controls={id}
+              onClick={function() { props.toggle(item.key); }}>
+              {item.icon && <span className="xeplr-expander-icon" aria-hidden="true">{item.icon}</span>}
+              <span className="xeplr-expander-title">{item.title}</span>
+              {item.summary && <span className="xeplr-expander-summary">{item.summary}</span>}
+              <svg className="xeplr-expander-chevron" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true">
+                <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+              </svg>
+            </button>
+            {item.open && <div className="xeplr-expander-body" id={id}>{item.content}</div>}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/panel/designs/PanelSection.jsx

@@ -0,0 +1,43 @@
+import './panel.css';
+
+/**
+ * A card that groups one part of a settings panel: an icon, a title, an
+ * optional line under it, and the rows. Presentation only.
+ */
+export function PanelSection(props) {
+  return (
+    <section className={'xeplr-panel-section' + (props.className ? ' ' + props.className : '')}>
+      {(props.title || props.icon) && (
+        <header className="xeplr-panel-section-head">
+          {props.icon && <span className="xeplr-panel-section-icon" aria-hidden="true">{props.icon}</span>}
+          <div className="xeplr-panel-section-titles">
+            <h3 className="xeplr-panel-section-title">{props.title}</h3>
+            {props.subtitle && <div className="xeplr-panel-section-subtitle">{props.subtitle}</div>}
+          </div>
+          {props.actions && <div className="xeplr-panel-section-actions">{props.actions}</div>}
+        </header>
+      )}
+      <div className="xeplr-panel-section-body">{props.children}</div>
+    </section>
+  );
+}
+
+/**
+ * One row of a panel: the label on the left, the control on the right, and a
+ * line of help under the control. `stacked` puts the control under the label,
+ * for a control too wide to share the line (a colour picker).
+ */
+export function PanelField(props) {
+  return (
+    <div className={'xeplr-panel-field' + (props.stacked ? ' xeplr-panel-field-stacked' : '')}>
+      <label className="xeplr-panel-field-label" htmlFor={props.htmlFor}>
+        {props.label}
+        {props.badge && <span className="xeplr-panel-field-badge">{props.badge}</span>}
+      </label>
+      <div className="xeplr-panel-field-control">
+        {props.children}
+        {props.help && <div className="xeplr-panel-field-help">{props.help}</div>}
+      </div>
+    </div>
+  );
+}

package/src/panel/designs/SettingsTreeSample.jsx

@@ -0,0 +1,51 @@
+import './settingsTree.css';
+
+function Chevron() {
+  return (
+    <svg className="xeplr-tree-chevron" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+      <path d="M6 4l4 4-4 4" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+
+function Node(props) {
+  var n = props.node;
+  var top = n.depth === 0;
+  return (
+    <div className={'xeplr-tree-node ' + (top ? 'xeplr-tree-group' : 'xeplr-tree-item') + (n.open ? ' open' : '')}
+      data-depth={n.depth}>
+      <button type="button" className="xeplr-tree-head" aria-expanded={n.open}
+        onClick={function() { props.toggle(n.parentKey, n.key); }}>
+        {!top && <span className="xeplr-tree-dot" aria-hidden="true" />}
+        {n.icon && <span className={top ? 'xeplr-tree-tile' : 'xeplr-tree-icon'} aria-hidden="true">{n.icon}</span>}
+        <span className="xeplr-tree-title">{n.title}</span>
+        {n.count ? <span className="xeplr-tree-count">{n.count}</span> : null}
+        <Chevron />
+      </button>
+      {n.open && (n.content || n.children) && (
+        <div className="xeplr-tree-body">
+          {n.content && <div className="xeplr-tree-content">{n.content}</div>}
+          {n.children && (
+            <div className="xeplr-tree-children">
+              {n.children.map(function(c) { return <Node key={c.key} node={c} toggle={props.toggle} />; })}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * SettingsTree — design. Top-level groups are cards (an icon tile, a title,
+ * how many settings are set, a chevron); an open group is tinted with an
+ * accent bar, its branches listed on a dotted rail. Everything from
+ * useSettingsTreeController.
+ */
+export default function SettingsTreeSample(props) {
+  return (
+    <div className="xeplr-tree">
+      {props.nodes.map(function(n) { return <Node key={n.key} node={n} toggle={props.toggle} />; })}
+    </div>
+  );
+}

package/src/panel/designs/index.js

@@ -0,0 +1,3 @@
+export { PanelSection, PanelField } from './PanelSection.jsx';
+export { default as ExpandersSample } from './ExpandersSample.jsx';
+export { default as SettingsTreeSample } from './SettingsTreeSample.jsx';

package/src/panel/designs/panel.css

@@ -0,0 +1,72 @@
+/* A settings panel: section cards, label-left rows, expanders. Uses the
+   --xeplr-* theme tokens; falls back to light values standalone. */
+
+.xeplr-panel-section {
+  border: 1px solid var(--xeplr-border-secondary, #eef0f4);
+  border-radius: 14px;
+  background: var(--xeplr-bg-primary, #fff);
+  box-shadow: 0 1px 2px rgba(16, 24, 40, .04), 0 2px 8px rgba(16, 24, 40, .04);
+  padding: 16px;
+}
+.xeplr-panel-section + .xeplr-panel-section { margin-top: 12px; }
+.xeplr-panel-section-head { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.xeplr-panel-section-icon {
+  width: 28px; height: 28px; border-radius: 8px; flex-shrink: 0;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: var(--xeplr-accent-soft, #eef1fd); color: var(--xeplr-accent, #4f5fd6);
+}
+.xeplr-panel-section-titles { flex: 1; min-width: 0; }
+.xeplr-panel-section-title {
+  margin: 0; font-size: 12px; font-weight: 600; letter-spacing: .06em; text-transform: uppercase;
+  color: var(--xeplr-text-secondary, #4b5563);
+}
+.xeplr-panel-section-subtitle { font-size: 12px; color: var(--xeplr-text-muted, #8a8f98); margin-top: 3px; }
+.xeplr-panel-section-body { display: flex; flex-direction: column; gap: 14px; }
+
+.xeplr-panel-field { display: grid; grid-template-columns: 112px minmax(0, 1fr); gap: 12px; align-items: start; }
+.xeplr-panel-field-stacked { grid-template-columns: minmax(0, 1fr); gap: 6px; }
+.xeplr-panel-field-label {
+  font-size: 13px; font-weight: 500; color: var(--xeplr-text-primary, #1f2937); padding-top: 8px;
+  display: flex; align-items: center; gap: 6px; min-width: 0;
+}
+.xeplr-panel-field-stacked .xeplr-panel-field-label { padding-top: 0; }
+.xeplr-panel-field-badge {
+  font-size: 10.5px; padding: 1px 6px; border-radius: 999px;
+  background: var(--xeplr-bg-secondary, #f3f4f6); color: var(--xeplr-text-muted, #6b7280);
+}
+.xeplr-panel-field-control { min-width: 0; display: flex; flex-direction: column; gap: 4px; }
+.xeplr-panel-field-control > select,
+.xeplr-panel-field-control > input:not([type="checkbox"]):not([type="radio"]) { width: 100%; box-sizing: border-box; }
+.xeplr-panel-field-help { font-size: 12px; line-height: 1.45; color: var(--xeplr-text-muted, #8a8f98); }
+
+.xeplr-expanders { display: flex; flex-direction: column; gap: 8px; }
+.xeplr-expander {
+  border: 1px solid var(--xeplr-border-secondary, #eef0f4); border-radius: 12px;
+  background: var(--xeplr-bg-primary, #fff); overflow: hidden;
+}
+.xeplr-expander.open {
+  border-color: var(--xeplr-accent, #4f5fd6);
+  box-shadow: 0 0 0 3px var(--xeplr-accent-soft, #eef1fd);
+}
+.xeplr-expander.open > .xeplr-expander-head { background: var(--xeplr-accent-soft, #eef1fd); }
+.xeplr-expander-head {
+  width: 100%; display: flex; align-items: center; gap: 10px; padding: 11px 14px;
+  background: transparent; border: 0; cursor: pointer; text-align: left; font: inherit;
+  color: var(--xeplr-text-primary, #1f2937);
+}
+.xeplr-expander-head:hover { background: var(--xeplr-bg-secondary, #f7f8fa); }
+.xeplr-expander-icon { display: inline-flex; color: var(--xeplr-text-muted, #6b7280); }
+.xeplr-expander.open .xeplr-expander-icon { color: var(--xeplr-accent, #4f5fd6); }
+.xeplr-expander-title { font-size: 13.5px; font-weight: 600; }
+.xeplr-expander.open .xeplr-expander-title { color: var(--xeplr-accent, #4f5fd6); }
+.xeplr-expander-summary {
+  margin-left: auto; font-size: 11.5px; color: var(--xeplr-text-muted, #6b7280);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0;
+}
+.xeplr-expander-chevron { flex-shrink: 0; color: var(--xeplr-text-muted, #6b7280); transition: transform .15s; }
+.xeplr-expander-title + .xeplr-expander-chevron { margin-left: auto; }
+.xeplr-expander.open .xeplr-expander-chevron { transform: rotate(180deg); }
+.xeplr-expander-body {
+  padding: 14px; border-top: 1px solid var(--xeplr-border-secondary, #eef0f4);
+  display: flex; flex-direction: column; gap: 12px;
+}

package/src/panel/designs/settingsTree.css

@@ -0,0 +1,69 @@
+/* A settings tree: groups as cards, branches on a dotted rail. Uses the
+   --xeplr-* theme tokens; falls back to light values standalone. */
+
+.xeplr-tree { display: flex; flex-direction: column; gap: 10px; }
+
+.xeplr-tree-group {
+  position: relative;
+  border: 1px solid var(--xeplr-border-secondary, #eceef3);
+  border-radius: 12px;
+  background: var(--xeplr-bg-primary, #fff);
+  box-shadow: 0 1px 2px rgba(16, 24, 40, .04);
+  overflow: hidden;
+}
+.xeplr-tree-group.open { box-shadow: 0 2px 10px rgba(16, 24, 40, .06); }
+/* The accent bar down the left of the open group. */
+.xeplr-tree-group.open::before {
+  content: ''; position: absolute; left: 0; top: 0; height: 52px; width: 3px;
+  background: var(--xeplr-accent, #3b5bdb); border-radius: 0 3px 3px 0;
+}
+
+.xeplr-tree-head {
+  width: 100%; display: flex; align-items: center; gap: 12px;
+  border: 0; background: transparent; cursor: pointer; text-align: left;
+  font: inherit; color: var(--xeplr-text-primary, #111827);
+}
+.xeplr-tree-group > .xeplr-tree-head { min-height: 52px; padding: 8px 14px 8px 12px; }
+.xeplr-tree-group > .xeplr-tree-head:hover { background: var(--xeplr-bg-secondary, #f8f9fb); }
+.xeplr-tree-group.open > .xeplr-tree-head { background: var(--xeplr-accent-soft, #edf2ff); }
+.xeplr-tree-group > .xeplr-tree-head .xeplr-tree-title { font-size: 14px; font-weight: 600; }
+
+.xeplr-tree-tile {
+  width: 32px; height: 32px; flex-shrink: 0; border-radius: 8px;
+  display: inline-flex; align-items: center; justify-content: center;
+  background: var(--xeplr-accent-soft, #edf2ff); color: var(--xeplr-accent, #3b5bdb);
+}
+.xeplr-tree-group.open .xeplr-tree-tile { background: var(--xeplr-bg-primary, #fff); }
+.xeplr-tree-title { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.xeplr-tree-count {
+  font-size: 11.5px; font-weight: 600; padding: 1px 8px; border-radius: 999px;
+  background: var(--xeplr-accent-soft, #edf2ff); color: var(--xeplr-accent, #3b5bdb);
+}
+.xeplr-tree-chevron { margin-left: auto; flex-shrink: 0; color: var(--xeplr-text-muted, #6b7280); transition: transform .15s; }
+.xeplr-tree-node.open > .xeplr-tree-head .xeplr-tree-chevron { transform: rotate(90deg); color: var(--xeplr-accent, #3b5bdb); }
+
+.xeplr-tree-body { padding: 4px 8px 8px; }
+.xeplr-tree-content { padding: 8px 6px; display: flex; flex-direction: column; gap: 10px; }
+
+/* Branches: a dotted rail on the left, a dot per branch on it. */
+.xeplr-tree-children { position: relative; padding-left: 26px; }
+.xeplr-tree-children::before {
+  content: ''; position: absolute; left: 11px; top: 14px; bottom: 14px;
+  border-left: 1px dashed var(--xeplr-border-primary, #d9dde5);
+}
+.xeplr-tree-item + .xeplr-tree-item { border-top: 1px solid var(--xeplr-border-secondary, #f0f1f4); }
+.xeplr-tree-item > .xeplr-tree-head { position: relative; min-height: 42px; padding: 6px 10px; border-radius: 8px; }
+.xeplr-tree-item > .xeplr-tree-head:hover { background: var(--xeplr-bg-secondary, #f6f7f9); }
+.xeplr-tree-item.open > .xeplr-tree-head { background: var(--xeplr-accent-soft, #edf2ff); }
+.xeplr-tree-item > .xeplr-tree-head .xeplr-tree-title { font-size: 13.5px; font-weight: 500; }
+.xeplr-tree-dot {
+  position: absolute; left: -18px; top: 50%; width: 7px; height: 7px; margin-top: -3.5px;
+  border-radius: 50%; background: var(--xeplr-border-primary, #c9ced8);
+}
+.xeplr-tree-item.open > .xeplr-tree-head .xeplr-tree-dot {
+  width: 9px; height: 9px; margin-top: -4.5px; left: -19px; background: var(--xeplr-accent, #3b5bdb);
+}
+.xeplr-tree-icon { display: inline-flex; color: var(--xeplr-text-secondary, #4b5563); flex-shrink: 0; }
+.xeplr-tree-item.open > .xeplr-tree-head .xeplr-tree-icon,
+.xeplr-tree-item.open > .xeplr-tree-head .xeplr-tree-title { color: var(--xeplr-accent, #3b5bdb); }
+.xeplr-tree-item > .xeplr-tree-body { padding: 4px 0 8px; }

package/src/panel/pages.jsx

@@ -0,0 +1,18 @@
+import { useExpandersController } from './useExpandersController.js';
+import { useSettingsTreeController } from './useSettingsTreeController.js';
+import ExpandersSample from './designs/ExpandersSample.jsx';
+import SettingsTreeSample from './designs/SettingsTreeSample.jsx';
+import { useDesignValidator } from '../fileUpload/validateDesign.js';
+import { EXPANDERS_RULES, SETTINGS_TREE_RULES } from './validateDesign.js';
+
+export function ExpandersPage(props) {
+  var controller = useExpandersController(props);
+  var ref = useDesignValidator('ExpandersPage', EXPANDERS_RULES);
+  return <div ref={ref}><ExpandersSample {...controller} /></div>;
+}
+
+export function SettingsTreePage(props) {
+  var controller = useSettingsTreeController(props);
+  var ref = useDesignValidator('SettingsTreePage', SETTINGS_TREE_RULES);
+  return <div ref={ref}><SettingsTreeSample {...controller} /></div>;
+}

package/src/panel/panel.js

@@ -0,0 +1,48 @@
+// Panel — model. Which expanders of a settings panel are open. A panel opens
+// one at a time by default (opening one closes the rest), or any number with
+// `multiple`. No React here.
+
+/** The open keys after `key` is clicked. */
+export function toggleOpen(open, key, multiple) {
+  var isOpen = open.indexOf(key) !== -1;
+  if (multiple) return isOpen ? open.filter(function(k) { return k !== key; }) : open.concat([key]);
+  return isOpen ? [] : [key];
+}
+
+/** The keys open at first: `initial` (a key or a list), else the first item, kept to known keys. */
+export function initialOpen(items, initial, multiple) {
+  var keys = items.map(function(i) { return i.key; });
+  var wanted = initial === undefined ? keys.slice(0, 1) : [].concat(initial || []);
+  wanted = wanted.filter(function(k) { return keys.indexOf(k) !== -1; });
+  return multiple ? wanted : wanted.slice(0, 1);
+}
+
+// ── Settings tree ─────────────────────────────────────────────────────────
+// Which branch is open at each level: { [parentKey]: openChildKey }, the root's
+// parent being ''. One open per level, so opening a sibling closes the other
+// and a deep tree never becomes one long scroll.
+
+/** The open map after `key` (a child of `parentKey`) is clicked. */
+export function toggleBranch(open, parentKey, key) {
+  var next = Object.assign({}, open);
+  if (next[parentKey] === key) delete next[parentKey];
+  else next[parentKey] = key;
+  return next;
+}
+
+/**
+ * The nodes with `open` and `depth` filled in, all the way down. A node is
+ * { key, title, icon?, count?, content?, children? }.
+ */
+export function decorateTree(nodes, open, parentKey, depth) {
+  parentKey = parentKey || '';
+  depth = depth || 0;
+  return (nodes || []).map(function(n) {
+    return Object.assign({}, n, {
+      parentKey: parentKey,
+      depth: depth,
+      open: open[parentKey] === n.key,
+      children: n.children && n.children.length ? decorateTree(n.children, open, n.key, depth + 1) : null
+    });
+  });
+}

package/src/panel/useExpandersController.js

@@ -0,0 +1,23 @@
+import { useState } from 'react';
+import { toggleOpen, initialOpen } from './panel.js';
+
+/**
+ * Expanders — controller. A list of titled parts of a panel, opened one at a
+ * time unless `multiple`. No JSX here.
+ *
+ * @param {object} props
+ * @param {Array<{key, title, summary?, icon?, content}>} props.items
+ * @param {string|string[]|null} [props.initial] - open at first (default: the first item)
+ * @param {boolean} [props.multiple] - let several be open together
+ */
+export function useExpandersController(props) {
+  var items = props.items || [];
+  var multiple = Boolean(props.multiple);
+  var state = useState(function() { return initialOpen(items, props.initial, multiple); });
+  var open = state[0];
+
+  return {
+    items: items.map(function(i) { return Object.assign({}, i, { open: open.indexOf(i.key) !== -1 }); }),
+    toggle: function(key) { state[1](function(o) { return toggleOpen(o, key, multiple); }); }
+  };
+}

package/src/panel/useSettingsTreeController.js

@@ -0,0 +1,18 @@
+import { useState } from 'react';
+import { toggleBranch, decorateTree } from './panel.js';
+
+/**
+ * SettingsTree — controller. Nested groups of settings, one open per level.
+ * No JSX here.
+ *
+ * @param {object} props
+ * @param {Array<{key, title, icon?, count?, content?, children?}>} props.nodes
+ * @param {object} [props.initial] - { [parentKey]: openChildKey }, root parent ''
+ */
+export function useSettingsTreeController(props) {
+  var state = useState(props.initial || {});
+  return {
+    nodes: decorateTree(props.nodes, state[0]),
+    toggle: function(parentKey, key) { state[1](function(o) { return toggleBranch(o, parentKey, key); }); }
+  };
+}

package/src/panel/validateDesign.js

@@ -0,0 +1,9 @@
+// An expanders design must give each item a header that opens it.
+export var EXPANDERS_RULES = [
+  { selector: '.xeplr-expander-head, [aria-expanded]', label: 'A header per item that opens it' }
+];
+
+// A settings tree design must give each node a header that opens it.
+export var SETTINGS_TREE_RULES = [
+  { selector: '.xeplr-tree-head, [aria-expanded]', label: 'A header per node that opens it' }
+];