@makoai/app-sdk 2.19.0 → 2.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ui-core.js CHANGED
@@ -369,6 +369,171 @@ export function multiSelectText(value, options, allLabel = "All", many = n => `$
369
369
  return many(selected.length);
370
370
  }
371
371
 
372
+ // ---------------------------------------------------------------------------
373
+ // Filter trees (2.20): the model behind FilterItems and MultiSelect
374
+ // ---------------------------------------------------------------------------
375
+ // Options form a tree ({ value, label, children? }); a flat list is a one-level
376
+ // tree. A selection is a list of leaf values, and [] means every leaf (All).
377
+ // Groups never sit in a selection: a group is ticked when all its leaves are.
378
+ // `none` is the open menu's "nothing ticked" draft: a click on a full All
379
+ // unticks every row. It emits nothing (an empty filter still means
380
+ // everything): the data keeps its selection until a row is ticked.
381
+
382
+ /** Every leaf value under `options`, in menu order. */
383
+ export function filterLeaves(options) {
384
+ return options.flatMap(o => (o.children ? filterLeaves(o.children) : [o.value]));
385
+ }
386
+
387
+ /** The leaves under a node (a leaf is its own). */
388
+ export function filterLeavesOf(node) {
389
+ return node.children ? filterLeaves(node.children) : [node.value];
390
+ }
391
+
392
+ /** The node with `value` anywhere in the tree. */
393
+ export function filterFind(options, value) {
394
+ for (const o of options) {
395
+ if (o.value === value) return o;
396
+ const hit = o.children && filterFind(o.children, value);
397
+ if (hit) return hit;
398
+ }
399
+ return undefined;
400
+ }
401
+
402
+ /**
403
+ * A selection in menu order; [] when it holds every leaf. Values the options
404
+ * don't list (a URL pick before its options load, or one the current date
405
+ * range lacks) are kept at the end, so the trigger never reads "All" over
406
+ * filtered data and the next tick does not drop them.
407
+ */
408
+ export function filterNormalize(options, picked) {
409
+ const set = new Set(picked);
410
+ const leaves = filterLeaves(options);
411
+ const known = new Set(leaves);
412
+ const out = leaves.filter(v => set.has(v));
413
+ const unknown = [...set].filter(v => !known.has(v));
414
+ if (leaves.length > 0 && out.length === leaves.length && !unknown.length) return [];
415
+ return [...out, ...unknown];
416
+ }
417
+
418
+ /** A node's tick: "on" when every leaf under it is picked, "mixed" when some are, "off" when none (or in the draft). */
419
+ export function filterTick(node, selected, none = false) {
420
+ const ls = filterLeavesOf(node);
421
+ // A group with no children yet (still loading) picks nothing: never "on".
422
+ if (none || !ls.length) return "off";
423
+ if (!selected.length) return "on";
424
+ const on = ls.filter(v => selected.includes(v)).length;
425
+ return on === ls.length ? "on" : on ? "mixed" : "off";
426
+ }
427
+
428
+ /** The All row's tick: "on" with every leaf picked, "mixed" with some, "off" in the draft. */
429
+ export function filterAllTick(selected, none = false) {
430
+ return none ? "off" : selected.length ? "mixed" : "on";
431
+ }
432
+
433
+ /**
434
+ * A click on All. Full All goes to the draft ({ none: true }); a partial All
435
+ * or the draft ticks every row ({ selected: [] }).
436
+ */
437
+ export function filterToggleAll(selected, none = false) {
438
+ return filterAllTick(selected, none) === "on" ? { none: true, selected } : { none: false, selected: [] };
439
+ }
440
+
441
+ /**
442
+ * A click on a node: off when all its leaves are ticked, else on. From the
443
+ * draft a tick picks that node alone. When the click leaves nothing ticked
444
+ * the result is the draft ({ none: true }) and the selection is unchanged.
445
+ */
446
+ export function filterToggle(options, selected, node, none = false) {
447
+ const ls = filterLeavesOf(node);
448
+ if (none) return { none: false, selected: filterNormalize(options, ls) };
449
+ const current = selected.length ? selected : filterLeaves(options);
450
+ const next = filterTick(node, selected) === "on" ? current.filter(v => !ls.includes(v)) : [...current, ...ls];
451
+ return next.length ? { none: false, selected: filterNormalize(options, next) } : { none: true, selected };
452
+ }
453
+
454
+ /** The one node whose leaves are exactly the pick (a leaf, or a whole group), else undefined. */
455
+ export function filterPickedNode(options, selected) {
456
+ const want = new Set(selected);
457
+ const walk = list => {
458
+ for (const o of list) {
459
+ const ls = filterLeavesOf(o);
460
+ if (ls.length === want.size && ls.every(v => want.has(v))) return o;
461
+ if (o.children && ls.some(v => want.has(v))) return walk(o.children);
462
+ }
463
+ return undefined;
464
+ };
465
+ return walk(options);
466
+ }
467
+
468
+ /**
469
+ * The trigger text: the All label; the one picked node's label ("404 Not
470
+ * found", a whole group "OpenAI"); for a flat list "N selected" (`many(n)`);
471
+ * for a tree its picked parts ("Pages + Assets: Images").
472
+ */
473
+ export function filterText(options, selected, allLabel = "All", many = n => `${n} selected`) {
474
+ if (!selected.length) return allLabel;
475
+ const one = filterPickedNode(options, selected);
476
+ if (one) return one.label;
477
+ if (selected.length === 1) return selected[0]; // one value the options don't list (yet)
478
+ if (!options.some(o => o.children)) return many(selected.length);
479
+ const parts = list =>
480
+ list.flatMap(o => {
481
+ const st = filterTick(o, selected);
482
+ if (st === "on") return [o.label];
483
+ return st === "mixed" && o.children ? parts(o.children) : [];
484
+ });
485
+ // A value the options don't list (yet) reads as itself, never as All or "".
486
+ const unknown = selected.filter(v => !filterFind(options, v));
487
+ return [
488
+ ...options.flatMap(o => {
489
+ const st = filterTick(o, selected);
490
+ if (st === "on") return [o.label];
491
+ if (st === "mixed" && o.children) return [`${o.label}: ${parts(o.children).join(", ")}`];
492
+ return [];
493
+ }),
494
+ ...unknown,
495
+ ].join(" + ");
496
+ }
497
+
498
+ const sameSet = (a, b) => a.length === b.length && a.every(v => b.includes(v));
499
+
500
+ /**
501
+ * The URL value of a selection: "" for the filter's default, "all" for every
502
+ * leaf (when the default is narrower), else a whole group by its own value
503
+ * and a partial one by its picked children, comma-separated.
504
+ */
505
+ export function filterToParam(options, selectedIn, defaultsIn = []) {
506
+ // All emitted as every leaf (emptyMeansAll false) compares as [].
507
+ const selected = filterNormalize(options, selectedIn);
508
+ const defaults = filterNormalize(options, defaultsIn);
509
+ if (sameSet(selected, defaults)) return "";
510
+ if (!selected.length) return "all";
511
+ const walk = list =>
512
+ list.flatMap(o => {
513
+ const st = filterTick(o, selected);
514
+ if (st === "on") return [o.value];
515
+ return st === "mixed" && o.children ? walk(o.children) : [];
516
+ });
517
+ const unknown = selected.filter(v => !filterFind(options, v));
518
+ return [...walk(options), ...unknown].join(",");
519
+ }
520
+
521
+ /**
522
+ * A URL value back to a selection. `legacy` maps former values onto node
523
+ * values first. Values the options don't list are kept (a URL pick read
524
+ * before its options load stays a pick). Missing or empty: the default.
525
+ */
526
+ export function filterFromParam(options, raw, defaults = [], legacy = {}) {
527
+ if (raw == null || raw === "") return defaults;
528
+ if (raw === "all") return [];
529
+ const picked = raw.split(",").flatMap(v => {
530
+ const node = filterFind(options, legacy[v] ?? v);
531
+ return node ? filterLeavesOf(node) : [v];
532
+ });
533
+ if (!picked.length) return defaults;
534
+ return filterNormalize(options, picked);
535
+ }
536
+
372
537
  // ---------------------------------------------------------------------------
373
538
  // One open popover at a time
374
539
  // ---------------------------------------------------------------------------
package/ui.css CHANGED
@@ -286,6 +286,11 @@ button, input, select, textarea { font-family: inherit; }
286
286
  .mk-ms-value { display: flex; align-items: center; gap: 6px; min-width: 0; overflow: hidden; }
287
287
  /* The trigger reads "All", the one selected label, or "N selected". */
288
288
  .mk-ms-text { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
289
+ /* The trigger is as wide as its longest probe (every label it can show): picks never move the bar. */
290
+ .mk-ms-fit { display: inline-grid; grid-template-columns: minmax(0, auto); min-width: 0; text-align: left; }
291
+ .mk-ms-fit > * { grid-area: 1 / 1; white-space: nowrap; }
292
+ .mk-ms-probe { visibility: hidden; height: 0; overflow: hidden; }
293
+ .mk-ms-fit > .mk-ms-text { width: 0; min-width: 100%; }
289
294
  .mk-ms-caret { color: var(--muted-foreground); flex-shrink: 0; transition: transform .15s ease; }
290
295
  .mk-ms-trigger.open .mk-ms-caret { transform: rotate(180deg); }
291
296
  .mk-ms-menu {
@@ -301,7 +306,11 @@ button, input, select, textarea { font-family: inherit; }
301
306
  }
302
307
  .mk-ms-opt:hover, .mk-ms-opt:focus-visible { background: var(--accent); outline: none; }
303
308
  .mk-ms-opt.active { font-weight: 500; }
304
- .mk-ms-label { flex: 1; }
309
+ .mk-ms-label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
310
+ /* FilterItems: the rows of one filter, in a MultiSelect or an app's own menu. */
311
+ .mk-ms-items { display: flex; flex-direction: column; gap: 1px; }
312
+ .mk-ms-all { font-weight: 500; }
313
+ .mk-ms-group .mk-ms-label { font-weight: 500; }
305
314
  /* The kit's one checkbox (Checkbox, MultiSelect rows): theme tokens only. */
306
315
  .mk-ms-box {
307
316
  display: inline-flex; align-items: center; justify-content: center;
@@ -319,6 +328,12 @@ button, input, select, textarea { font-family: inherit; }
319
328
  }
320
329
  .mk-ms-opt:hover .mk-ms-only, .mk-ms-opt:focus-within .mk-ms-only { visibility: visible; }
321
330
  .mk-ms-only:hover { color: var(--foreground); background: var(--muted); }
331
+ /* FilterMenu (@makoai/app-sdk/menu): the "Only" action shows on the hovered or highlighted row, as in the apps' NestedFilterMenu. */
332
+ .mk-fm-only { visibility: hidden; font-size: 12px; color: var(--muted-foreground); padding: 0 4px; border-radius: 4px; cursor: pointer; }
333
+ .mk-fm-only:hover { color: var(--foreground); background: var(--muted); }
334
+ .mk-fm-row:hover .mk-fm-only, .mk-fm-row:focus .mk-fm-only, .mk-fm-row[data-highlighted] .mk-fm-only { visibility: visible; }
335
+ /* The phone Filters menu: a group row that opens in place (drill) keeps its chevron at the end. */
336
+ .mk-fm-drill { padding-right: 4px; }
322
337
  @media (max-width: 640px) {
323
338
  .mk-ms-trigger { height: 38px; }
324
339
  .mk-ms-opt { padding: 10px 8px; }
package/ui.d.ts CHANGED
@@ -69,19 +69,66 @@ export interface MultiSelectOption<V extends string = string> {
69
69
  label: string;
70
70
  /** A colour swatch shown next to the label (e.g. a chart series colour). */
71
71
  color?: string;
72
+ /** What the option covers, shown on hover. */
73
+ title?: string;
74
+ /** A group (2.20): its row ticks every leaf under it; hover submenus: FilterMenu in `@makoai/app-sdk/menu`. */
75
+ children?: ReadonlyArray<MultiSelectOption<V>>;
72
76
  }
73
77
 
78
+ /** A node's tick in a filter tree. */
79
+ export type FilterTick = "on" | "mixed" | "off";
80
+
81
+ /**
82
+ * The rows of one filter (2.20): All, a separator, one tri-state row per
83
+ * option, a group's children indented under it. Use it in an app's own composite menu
84
+ * (several filters in one dropdown); MultiSelect renders it in its popover.
85
+ * Drop-in for the apps' NestedFilterItems (`selected` = `value`).
86
+ */
87
+ export interface FilterItemsProps<V extends string = string> {
88
+ options: ReadonlyArray<V | MultiSelectOption<V>>;
89
+ /** The selected leaf values; empty or every leaf = All. */
90
+ value?: readonly V[];
91
+ /** Alias of `value` (NestedFilterItems). */
92
+ selected?: readonly V[];
93
+ onChange: (next: V[]) => void;
94
+ allLabel?: string;
95
+ emptyMeansAll?: boolean;
96
+ showOnly?: boolean;
97
+ /** The "nothing ticked" draft, when the parent shows it; else FilterItems keeps it. */
98
+ none?: boolean;
99
+ onNoneChange?: (none: boolean) => void;
100
+ className?: string;
101
+ "aria-label"?: string;
102
+ }
103
+ export function FilterItems<V extends string = string>(props: FilterItemsProps<V>): React.ReactElement;
104
+
74
105
  export interface MultiSelectProps<V extends string = string> {
106
+ /** Strings, options, or groups with `children` (2.20): a flat list is a one-level tree. */
75
107
  options: ReadonlyArray<V | MultiSelectOption<V>>;
76
108
  /**
77
- * The selected values. Empty, or every option, means "All": the All row is
78
- * ticked and every option row unticked. Under All a click on an option
79
- * selects only that option; unticking the last option, or ticking the last
80
- * missing one, returns to All.
109
+ * The selected leaf values. Empty, or every leaf, means "All". The All rule
110
+ * (2.20): under All every row is ticked; unticking one leaves All partial
111
+ * (–); a click on a full All unticks every row (a draft that emits
112
+ * nothing: the trigger reads `noneLabel` and the first tick picks that row
113
+ * alone); a click on a partial All ticks every row.
81
114
  */
82
- value: readonly V[];
115
+ value?: readonly V[];
116
+ /** Alias of `value` (drop-in for NestedFilterMenu). */
117
+ selected?: readonly V[];
83
118
  onChange: (next: V[]) => void;
84
119
  allLabel?: string;
120
+ /** Trigger text while nothing is ticked. Default "None". */
121
+ noneLabel?: string;
122
+ /** Replaces the trigger text. */
123
+ summary?: string;
124
+ /** The texts the trigger's width is fixed to. Default: All, top-level labels, "N selected", none. */
125
+ sizeTo?: readonly string[];
126
+ /** More texts the width also fits. */
127
+ probes?: readonly string[];
128
+ /** A class on the trigger button (e.g. a fixed width). */
129
+ triggerClassName?: string;
130
+ /** Alias of `aria-label` (NestedFilterMenu). */
131
+ label?: string;
85
132
  /**
86
133
  * What All emits. true (default): []. false: every option's value.
87
134
  * Both spellings display as All either way.
@@ -106,6 +153,46 @@ export function MultiSelect<V extends string = string>(props: MultiSelectProps<V
106
153
  */
107
154
  export function Checkbox(props: { checked?: boolean | "mixed"; className?: string }): React.ReactElement;
108
155
 
156
+ /** Every leaf value under a filter tree, in menu order. */
157
+ export function filterLeaves<V extends string>(options: ReadonlyArray<MultiSelectOption<V>>): V[];
158
+ /** The leaves under a node (a leaf is its own). */
159
+ export function filterLeavesOf<V extends string>(node: MultiSelectOption<V>): V[];
160
+ /** The node with `value` anywhere in the tree. */
161
+ export function filterFind<V extends string>(options: ReadonlyArray<MultiSelectOption<V>>, value: V): MultiSelectOption<V> | undefined;
162
+ /** A selection in menu order; [] when it holds every leaf. */
163
+ export function filterNormalize<V extends string>(options: ReadonlyArray<MultiSelectOption<V>>, picked: Iterable<V>): V[];
164
+ /** A node's tick; `none` = the nothing-ticked draft. */
165
+ export function filterTick<V extends string>(node: MultiSelectOption<V>, selected: readonly V[], none?: boolean): FilterTick;
166
+ /** The All row's tick. */
167
+ export function filterAllTick(selected: readonly string[], none?: boolean): FilterTick;
168
+ /** A click on All: full → the draft; partial or draft → every row. */
169
+ export function filterToggleAll<V extends string>(selected: readonly V[], none?: boolean): { none: boolean; selected: V[] };
170
+ /** A click on a node; leaving nothing ticked returns the draft with the selection unchanged. */
171
+ export function filterToggle<V extends string>(
172
+ options: ReadonlyArray<MultiSelectOption<V>>,
173
+ selected: readonly V[],
174
+ node: MultiSelectOption<V>,
175
+ none?: boolean,
176
+ ): { none: boolean; selected: V[] };
177
+ /** The one node whose leaves are exactly the pick. */
178
+ export function filterPickedNode<V extends string>(options: ReadonlyArray<MultiSelectOption<V>>, selected: readonly V[]): MultiSelectOption<V> | undefined;
179
+ /** Trigger text: All label, the one node, "N selected" (flat), or the picked parts (tree). */
180
+ export function filterText<V extends string>(
181
+ options: ReadonlyArray<MultiSelectOption<V>>,
182
+ selected: readonly V[],
183
+ allLabel?: string,
184
+ many?: (n: number) => string,
185
+ ): string;
186
+ /** URL value: "" for the default, "all", else whole groups by value and partial ones by children. */
187
+ export function filterToParam<V extends string>(options: ReadonlyArray<MultiSelectOption<V>>, selected: readonly V[], defaults?: readonly V[]): string;
188
+ /** A URL value back to a selection; `legacy` maps former values first. */
189
+ export function filterFromParam<V extends string>(
190
+ options: ReadonlyArray<MultiSelectOption<V>>,
191
+ raw: string | null | undefined,
192
+ defaults?: readonly V[],
193
+ legacy?: Record<string, string>,
194
+ ): V[];
195
+
109
196
  /** Where a MultiSelect stands: `all` when the value is empty or holds every option (then `selected` is empty). */
110
197
  export function multiSelectState<V extends string>(
111
198
  value: readonly V[] | null | undefined,
@@ -395,3 +482,6 @@ export function csvDate(date: Date): string;
395
482
  export function csvToTsv(text: string): string;
396
483
  /** Download CSV text as a file. Works inside Mako's app frame. */
397
484
  export function saveCsv(filename: string, text: string): "downloaded" | "failed";
485
+
486
+ export { formatDate, formatTime, toDayKey, toInstant } from "./index";
487
+ export type { FormatDateOptions, FormatTimeOptions, TimeValue } from "./index";