@xeplr/ui-utils 1.0.7 → 1.0.9

package/README.md

@@ -100,15 +100,19 @@ 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)
 
 | hook | takes | returns |
 |---|---|---|
 | `useDropdownController(props)` | DropdownPage props | `mode, source, keys {id,name,extras}, searchable, canCreate, createLabel, creating, createError, createItem(name?), placeholder, disabled, items, filteredItems, selectedItems, selection, loading, error, query, isOpen, rootRef, isSelected(id), open, close, toggle, selectItem(id), removeSelection(id), clearSelection, handleSearch(e), refresh` |
-| `useDateRangeController(props)` | DateRangePage props | `tab, setTab, presets, value, label, range, single, setSingle, singleParsed, suggestions, applySuggestion(text), selectPreset(key), setRangeFrom, setRangeTo, commitSingle(close), clear, allowClear, inheritedLabel` |
+| `useDateRangeController(props)` | DateRangePage props | `tab, setTab, presets, value, label, range, single, setSingle, singleParsed, suggestions, applySuggestion(text), selectPreset(key), setRangeFrom, setRangeTo (edit the draft), applyRange(), rangeProblem, rangeDirty, commitSingle(close), clear, allowClear, inheritedLabel` |
 | `useRangeFieldController(props)` | RangeFieldPage props | `fromLabel, toLabel, from, to`. `from` and `to` are each a `useDateFieldController` result. |
 | `useDateFieldController(props)` | DateFieldPage props | `type, inputType, raw, age, error, placeholder, disabled, min, max, handleChange` |
 | `useNumberFieldController(props)` | NumberFieldPage props | `type, raw, numeric, error, placeholder, disabled, decimals, formatDisplay, affix {list, selected, position, labelKey, valueKey} \| null, handleNumberChange, handleAffixChange, handleBlur` |
@@ -117,6 +121,9 @@ export default function SelectCompany() {
 | `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), 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)
@@ -129,11 +136,15 @@ export default function SelectCompany() {
 | `resolveDateValue` | `(selection, now?, options?) → { from, to } \| null` | Resolves a `quick` / `range` / `single` selection. `null` means no constraint. |
 | `dateValueLabel` | `(selection) → string \| null` | "Last month", "2022-01-01 → 2022-03-31", "From …", "Until …" |
 | `dateValueIsSet` | `(selection, now?) → boolean` | True only if the selection resolves to a range |
+| `rangeProblem` | `({ from, to }) → string \| null` | Why a typed range cannot be applied yet ("Choose a From or a To date", "From is after To"), or `null` |
 | `RANGE_TYPES`, `emptyRange`, `normalizeRange`, `rangeIsSet` | `['date','datetime']`, `() → {from:'',to:''}`, `(r) → {from,to}`, `(r) → boolean` | From/to helpers. A range with one side set counts as set. |
 | `DATE_TYPES`, `isValidISODate`, `calculateAge`, `inputTypeFor`, `toInputValue`, `validateBounds` | `['date','datetime','age']`, `(s)`, `(dob, now?)`, `(type)`, `(value, type)`, `(value, min, max) → { valid, error? }` | Date field helpers |
 | `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 |
 | `configureUpload`, `uploadFile` | `({ url, headers, getHeaders })`, `(files, { url, fieldName, extraData, onProgress }) → Promise` | Multipart upload over XHR |
@@ -154,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
 
@@ -189,12 +200,12 @@ export default function SelectCompany() {
 |---|---|---|---|
 | `value` | `{ kind: 'quick', preset } \| { kind: 'range', from, to } \| { kind: 'single', value } \| null` | `null` | The selection |
 | `onChange` | `(selection \| null) => void` | no-op | |
-| `onClose` | `() => void` | — | Called after a choice that ends the interaction: a preset, a suggestion, Enter in Single, or Clear |
+| `onClose` | `() => void` | — | Called after a choice that ends the interaction: a preset, a suggestion, Apply (or Enter) in Range or Single, or Clear |
 | `presets` | `[{ key, label }]` | `QUICK_PRESETS` | The Quick list. Only keys that `resolveQuickPreset` knows will resolve. |
 | `allowClear` | `boolean` | `true` | `false` removes the Clear button, and `clear()` refuses too |
 | `inheritedLabel` | `string` | — | Shows "Using …" when `value` is empty |
 
-**Every selection resolves to `{ from, to }`, including a single date.** "May 2022" becomes 1–31 May and "2022" becomes the whole year, so a consumer never has to ask which comparison was meant. The Range tab changes `onChange` on every edit, and one open side is allowed. The Single tab commits only once the text parses ("Not a date yet" otherwise), on blur or Enter. While you type, it suggests months and years, putting the committed year first. The financial-year presets use `fiscalStartMonth` (default April). The page itself does not pass that option, so change it by calling `resolveDateValue(value, now, { fiscalStartMonth })` where you consume the value.
+**Every selection resolves to `{ from, to }`, including a single date.** "May 2022" becomes 1–31 May and "2022" becomes the whole year, so a consumer never has to ask which comparison was meant. **The Range tab is applied, not taken as you type.** A browser date input holds a complete date while a year is half typed (`2` is `0002-01-01`), so committing each edit ran the host's query for the year 2. The inputs edit a draft, and `onChange` fires once, on **Apply** or Enter. Apply is disabled until the draft is valid (`rangeProblem`: something chosen, From not after To) and differs from what is applied. One open side is allowed. The Single tab commits only once the text parses ("Not a date yet" otherwise), on blur, Enter or Apply. While you type, it suggests months and years, putting the committed year first. The financial-year presets use `fiscalStartMonth` (default April). The page itself does not pass that option, so change it by calling `resolveDateValue(value, now, { fiscalStartMonth })` where you consume the value.
 
 ## RangeFieldPage
 
@@ -324,6 +335,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`:
@@ -394,17 +451,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 | — |
 
@@ -443,7 +504,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)
@@ -454,7 +515,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
@@ -463,7 +525,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.7",
+  "version": "1.0.9",
   "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/dateRange/dateRange.js

@@ -271,3 +271,22 @@ export function dateValueLabel(value) {
 export function dateValueIsSet(value, now) {
   return Boolean(resolveDateValue(value, now || new Date()))
 }
+
+/**
+ * Why a typed range cannot be applied yet, or null when it can.
+ *
+ * A browser date input holds a COMPLETE date while the year is still being
+ * typed ("2" is 0002-…), so a range is never taken as you type — it is
+ * applied (the Apply button, or Enter), and this is what Apply asks first.
+ * One side empty is fine: "everything since April" is a real range.
+ *
+ * @param {{from?: string, to?: string}} draft - ISO dates, either may be empty
+ * @returns {string|null}
+ */
+export function rangeProblem(draft) {
+  var from = (draft && draft.from) || '';
+  var to = (draft && draft.to) || '';
+  if (!from && !to) return 'Choose a From or a To date';
+  if (from && to && from > to) return 'From is after To';
+  return null;
+}

package/src/dateRange/designs/DateRangeSample.jsx

@@ -56,17 +56,30 @@ export default function DateRangeSample(props) {
 
       {props.tab === 'range' && (
         <div className="xeplr-daterange-body">
+          {/* Edited as a draft and applied — the inputs hold a full date while
+              a year is half typed, so taking each change ran the report for
+              the year 2. Enter in either input applies too. */}
           <label className="xeplr-daterange-field">
             <span>From</span>
-            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }} />
+            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }}
+              onKeyDown={function(e) { if (e.key === 'Enter') { e.preventDefault(); props.applyRange(); } }} />
           </label>
           <label className="xeplr-daterange-field">
             <span>To</span>
-            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }} />
+            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }}
+              onKeyDown={function(e) { if (e.key === 'Enter') { e.preventDefault(); props.applyRange(); } }} />
           </label>
           {/* One-sided is legitimate — "everything since April" is a real
               answer — so it is stated rather than blocked. */}
-          <div className="xeplr-daterange-note">Leave either side empty for an open-ended range.</div>
+          <div className="xeplr-daterange-note">
+            {props.rangeProblem && (props.range.from || props.range.to)
+              ? props.rangeProblem
+              : 'Leave either side empty for an open-ended range.'}
+          </div>
+          <div className="xeplr-daterange-actions">
+            <button type="button" className="xeplr-daterange-apply" data-xeplr-daterange-apply="range"
+              disabled={Boolean(props.rangeProblem) || !props.rangeDirty} onClick={props.applyRange}>Apply</button>
+          </div>
         </div>
       )}
 
@@ -117,6 +130,12 @@ export default function DateRangeSample(props) {
               ? (props.singleParsed ? props.singleParsed.from + ' → ' + props.singleParsed.to : 'Not a date yet')
               : 'A day, a whole month, or a whole year.'}
           </div>
+          <div className="xeplr-daterange-actions">
+            <button type="button" className="xeplr-daterange-apply" data-xeplr-daterange-apply="single"
+              disabled={!props.singleParsed}
+              // MOUSEDOWN: the input's onBlur would otherwise commit first.
+              onMouseDown={function(e) { e.preventDefault(); props.commitSingle(true); }}>Apply</button>
+          </div>
         </div>
       )}
 

package/src/dateRange/designs/dateRange.css

@@ -67,3 +67,15 @@
 }
 .xeplr-daterange-suggest button:hover { background: var(--xeplr-hover, #f4f5f8); }
 .xeplr-daterange-suggest-note { font-size: 11px; color: var(--xeplr-muted, #6b7280); }
+
+/* Apply — a typed range (or date) reaches the host only through this, or
+   Enter. Disabled while there is nothing new to apply, or it is not valid. */
+.xeplr-daterange-actions { display: flex; justify-content: flex-end; margin-top: 8px; }
+.xeplr-daterange-apply {
+  padding: 5px 14px; border-radius: 6px; cursor: pointer;
+  font-size: 12px; font-weight: 600;
+  border: 1px solid var(--xeplr-accent, #4f5fd6);
+  background: var(--xeplr-accent, #4f5fd6);
+  color: var(--xeplr-on-accent, #fff);
+}
+.xeplr-daterange-apply:disabled { opacity: 0.45; cursor: default; }

package/src/dateRange/useDateRangeController.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions } from './dateRange.js';
+import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions, rangeProblem } from './dateRange.js';
 
 /**
  * DateRange — controller. Owns which tab is open and the half-typed text; the
@@ -37,7 +37,21 @@ export function useDateRangeController(props) {
     if (value && value.kind === 'single') setSingle(value.value || '');
   }, [value]);
 
-  var range = value && value.kind === 'range' ? value : { from: '', to: '' };
+  // THE RANGE IS A DRAFT until it is applied. It used to be committed on
+  // every change of either input — and a date input holds a complete date
+  // while the year is half typed ("2" is 0002-01-01), so typing 2026 ran the
+  // report for the year 2. Now the inputs edit this draft, and applyRange
+  // (the Apply button, or Enter) commits it.
+  var committedRange = value && value.kind === 'range' ? value : null;
+  var draftState = useState({ from: committedRange ? committedRange.from || '' : '', to: committedRange ? committedRange.to || '' : '' });
+  var range = draftState[0];
+  var setRange = draftState[1];
+  // A range chosen elsewhere (a reset, another record) replaces the draft.
+  useEffect(function() {
+    if (value && value.kind === 'range') setRange({ from: value.from || '', to: value.to || '' });
+  }, [value]);
+  var rangeIssue = rangeProblem(range);
+  var rangeDirty = !committedRange || (committedRange.from || '') !== range.from || (committedRange.to || '') !== range.to;
   // Parsed as you type, so "May 202" reads as not-a-date-yet rather than
   // silently saving as nothing.
   var singleParsed = single ? parseSingleDate(single) : null;
@@ -71,11 +85,19 @@ export function useDateRangeController(props) {
   }
 
   function setRangeFrom(from) {
-    onChange({ kind: 'range', from: from, to: range.to || '' });
+    setRange(function(r) { return { from: from || '', to: r.to }; });
   }
 
   function setRangeTo(to) {
-    onChange({ kind: 'range', from: range.from || '', to: to });
+    setRange(function(r) { return { from: r.from, to: to || '' }; });
+  }
+
+  // Commits the draft. Refused while it has a problem (rangeProblem), so a
+  // custom design cannot apply a range Apply would have been disabled for.
+  function applyRange() {
+    if (rangeIssue) return;
+    onChange({ kind: 'range', from: range.from, to: range.to });
+    if (onClose) onClose();
   }
 
   // Only committed once it parses — a partial entry must not overwrite a good
@@ -110,6 +132,9 @@ export function useDateRangeController(props) {
     selectPreset: selectPreset,
     setRangeFrom: setRangeFrom,
     setRangeTo: setRangeTo,
+    applyRange: applyRange,
+    rangeProblem: rangeIssue,
+    rangeDirty: rangeDirty,
     commitSingle: commitSingle,
     clear: clear,
     allowClear: allowClear,

package/src/index.js

@@ -92,7 +92,8 @@ export {
   resolveQuickPreset,
   resolveDateValue,
   dateValueLabel,
-  dateValueIsSet
+  dateValueIsSet,
+  rangeProblem
 } from './dateRange/dateRange.js';
 
 // DateRange — controller
@@ -197,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' }
+];