@makoai/app-sdk 2.19.0 → 2.20.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.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,
package/ui.js CHANGED
@@ -22,6 +22,18 @@ import {
22
22
  csvToTsv,
23
23
  defaultColumnWidth,
24
24
  formatSeconds as fmtSecs,
25
+ filterAllTick,
26
+ filterFind,
27
+ filterFromParam,
28
+ filterLeaves,
29
+ filterLeavesOf,
30
+ filterNormalize,
31
+ filterPickedNode,
32
+ filterText,
33
+ filterTick,
34
+ filterToggle,
35
+ filterToggleAll,
36
+ filterToParam,
25
37
  multiSelectAll,
26
38
  multiSelectState,
27
39
  multiSelectText,
@@ -49,6 +61,18 @@ export {
49
61
  csvDate,
50
62
  csvToTsv,
51
63
  defaultColumnWidth,
64
+ filterAllTick,
65
+ filterFind,
66
+ filterFromParam,
67
+ filterLeaves,
68
+ filterLeavesOf,
69
+ filterNormalize,
70
+ filterPickedNode,
71
+ filterText,
72
+ filterTick,
73
+ filterToggle,
74
+ filterToggleAll,
75
+ filterToParam,
52
76
  multiSelectState,
53
77
  multiSelectText,
54
78
  multiSelectToggle,
@@ -687,44 +711,180 @@ export function Checkbox({ checked = false, className }) {
687
711
  );
688
712
  }
689
713
 
714
+ function toNode(o) {
715
+ const n = toOption(o);
716
+ return n.children ? { ...n, children: n.children.map(toNode) } : n;
717
+ }
718
+
719
+ const asChecked = t => (t === "on" ? true : t === "mixed" ? "mixed" : false);
720
+
721
+ /**
722
+ * The rows of a multi-select filter, without trigger or popover: the All row,
723
+ * a separator, then every option with a tri-state checkbox. MultiSelect
724
+ * renders them in its popover; an app renders them in its own composite menu
725
+ * (several filters folded into one dropdown on a phone), so every filter
726
+ * ticks and toggles alike.
727
+ *
728
+ * Options are strings, `{ value, label, color }`, or groups with `children`
729
+ * (a flat list is a one-level tree). A group row ticks its whole group and
730
+ * shows a dash when part of it is picked; its children follow it, indented.
731
+ * A tree that needs hover submenus is a FilterMenu (`@makoai/app-sdk/menu`).
732
+ *
733
+ * The All rule (2.20): with nothing filtered (`value` empty or holding every
734
+ * option) every row is ticked. Unticking one leaves All in the partial (–)
735
+ * state. A click on a full All unticks every row; a click on a partial All
736
+ * ticks every row. "Nothing ticked" is a draft: it emits nothing, the data
737
+ * keeps its selection until a row is ticked, and the first tick picks that
738
+ * row alone. Pass `none` / `onNoneChange` to show the draft elsewhere (the
739
+ * trigger); otherwise FilterItems keeps it.
740
+ */
741
+ export function FilterItems({
742
+ options,
743
+ value: valueProp,
744
+ selected: selectedProp,
745
+ onChange,
746
+ allLabel = "All",
747
+ emptyMeansAll = true,
748
+ showOnly = false,
749
+ none: noneProp,
750
+ onNoneChange,
751
+ className,
752
+ "aria-label": ariaLabel,
753
+ }) {
754
+ const value = valueProp ?? selectedProp;
755
+ const tree = options.map(toNode);
756
+ const leaves = filterLeaves(tree);
757
+ const selected = filterNormalize(tree, value ?? []);
758
+ const [ownNone, setOwnNone] = React.useState(false);
759
+ const none = noneProp ?? ownNone;
760
+ const setNone = onNoneChange ?? setOwnNone;
761
+ const emit = next => {
762
+ setNone(false);
763
+ onChange(next.length ? next : multiSelectAll(leaves, emptyMeansAll));
764
+ };
765
+ const apply = r => {
766
+ if (r.none) setNone(true);
767
+ else emit(r.selected);
768
+ };
769
+ const flip = node => apply(filterToggle(tree, selected, node, none));
770
+ const only = node => e => {
771
+ e.stopPropagation();
772
+ emit(filterNormalize(tree, filterLeavesOf(node)));
773
+ };
774
+ const dot = o => (o.color ? h("span", { className: "mk-ms-swatch", style: { background: o.color } }) : null);
775
+ const allTick = filterAllTick(selected, none);
776
+
777
+ const row = (node, depth) => {
778
+ const tick = filterTick(node, selected, none);
779
+ const group = Boolean(node.children);
780
+ const el = h(
781
+ "div",
782
+ {
783
+ key: node.value,
784
+ role: "option",
785
+ "aria-selected": tick === "on",
786
+ "aria-checked": asChecked(tick),
787
+ tabIndex: 0,
788
+ title: node.title,
789
+ className: cx("mk-ms-opt", tick !== "off" && "active", group && "mk-ms-group"),
790
+ style: depth ? { paddingLeft: 8 + depth * 20 } : undefined,
791
+ onClick: () => flip(node),
792
+ onKeyDown: e => {
793
+ if (e.key === "Enter" || e.key === " ") {
794
+ e.preventDefault();
795
+ e.stopPropagation();
796
+ flip(node);
797
+ }
798
+ },
799
+ },
800
+ h(Checkbox, { checked: asChecked(tick) }),
801
+ dot(node),
802
+ h("span", { className: "mk-ms-label" }, node.label),
803
+ showOnly && filterLeavesOf(node).length > 0 && h("button", { type: "button", className: "mk-ms-only", tabIndex: -1, onClick: only(node) }, "Only"),
804
+ );
805
+ return group ? [el, ...node.children.flatMap(c => row(c, depth + 1))] : [el];
806
+ };
807
+
808
+ return h(
809
+ "div",
810
+ { className: cx("mk-ms-items", className), role: "listbox", "aria-multiselectable": true, "aria-label": ariaLabel },
811
+ h(
812
+ "div",
813
+ {
814
+ role: "option",
815
+ "aria-selected": allTick === "on",
816
+ "aria-checked": asChecked(allTick),
817
+ tabIndex: 0,
818
+ className: cx("mk-ms-opt", "mk-ms-all", allTick !== "off" && "active"),
819
+ onClick: () => apply(filterToggleAll(selected, none)),
820
+ onKeyDown: e => {
821
+ if (e.key === "Enter" || e.key === " ") {
822
+ e.preventDefault();
823
+ e.stopPropagation();
824
+ apply(filterToggleAll(selected, none));
825
+ }
826
+ },
827
+ },
828
+ h(Checkbox, { checked: asChecked(allTick) }),
829
+ h("span", { className: "mk-ms-label" }, allLabel),
830
+ ),
831
+ h("div", { className: "mk-ms-sep" }),
832
+ ...tree.flatMap(o => row(o, 0)),
833
+ );
834
+ }
835
+
690
836
  /**
691
- * Multi-select filter (shadcn combobox look). Controlled: `value` is the
692
- * selected values, `onChange` gets the next array.
837
+ * Multi-select filter (shadcn combobox look) around FilterItems. Controlled:
838
+ * `value` is the selected leaf values, `onChange` gets the next array. See
839
+ * FilterItems for the All rule. `emptyMeansAll` (default true) only picks
840
+ * what All emits: [] by default, every leaf's value when false.
693
841
  *
694
- * The All rule: nothing is filtered when `value` is empty or holds every
695
- * option. The All row is then ticked and every option row unticked. A click
696
- * on an option under All selects only that option. Unticking the last
697
- * option, or ticking the last missing one, returns to All. The trigger reads
698
- * the All label, the one selected label, or "N selected".
842
+ * The trigger reads the All label, the one picked label (a leaf or a whole
843
+ * group), "N selected" for a flat list (`formatMany`), the picked parts for a
844
+ * tree ("Pages + Assets: Images"), or `noneLabel` while nothing is ticked;
845
+ * `summary` replaces that text. Its width is fixed to the longest of
846
+ * `sizeTo` (default: the All label, the top-level labels, "N selected" and
847
+ * the none label) plus `probes`, so a pick never moves the layout; a longer
848
+ * text ends in an ellipsis and stays whole in the title.
699
849
  *
700
- * `emptyMeansAll` (default true) only picks what All emits: [] by default,
701
- * every option's value when false.
850
+ * Drop-in for the apps' NestedFilterMenu: `selected` = `value`, `label` =
851
+ * `aria-label`, `triggerClassName`, `summary`, `probes`, `sizeTo`.
702
852
  */
703
853
  export function MultiSelect({
704
854
  options,
705
- value,
855
+ value: valueProp,
856
+ selected: selectedProp,
706
857
  onChange,
707
858
  allLabel = "All",
859
+ noneLabel = "None",
708
860
  emptyMeansAll = true,
709
861
  showOnly = false,
710
862
  formatMany,
863
+ summary,
864
+ sizeTo,
865
+ probes = [],
711
866
  align = "start",
712
867
  className,
713
- "aria-label": ariaLabel,
868
+ triggerClassName,
869
+ label,
870
+ "aria-label": ariaLabelProp,
714
871
  }) {
872
+ const value = valueProp ?? selectedProp;
873
+ const ariaLabel = ariaLabelProp ?? label;
715
874
  const [open, setOpen] = React.useState(false);
875
+ const [none, setNone] = React.useState(false);
716
876
  const ref = React.useRef(null);
717
877
  usePopover(open, setOpen, ref, align);
718
- const opts = options.map(toOption);
719
- const values = opts.map(o => o.value);
720
- const { all: allOn, selected } = multiSelectState(value, values);
721
- const text = multiSelectText(value, opts, allLabel, formatMany);
722
- const single = selected.length === 1 ? opts.find(o => o.value === selected[0]) : null;
723
-
724
- const toggle = v => onChange(multiSelectToggle(value, values, v, emptyMeansAll));
725
- const all = () => onChange(multiSelectAll(values, emptyMeansAll));
726
- const dot = o =>
727
- o?.color ? h("span", { className: "mk-ms-swatch", style: { background: o.color } }) : null;
878
+ React.useEffect(() => {
879
+ if (!open) setNone(false);
880
+ }, [open]);
881
+ const tree = options.map(toNode);
882
+ const selected = filterNormalize(tree, value ?? []);
883
+ const many = formatMany ?? (n => `${n} selected`);
884
+ const text = none ? noneLabel : (summary ?? filterText(tree, selected, allLabel, many));
885
+ const sizes = [...(sizeTo ?? [allLabel, ...tree.map(o => o.label), many(filterLeaves(tree).length), noneLabel]), ...probes];
886
+ const single = selected.length ? filterPickedNode(tree, selected) : null;
887
+ const dot = o => (o?.color ? h("span", { className: "mk-ms-swatch", style: { background: o.color } }) : null);
728
888
 
729
889
  return h(
730
890
  "div",
@@ -733,69 +893,43 @@ export function MultiSelect({
733
893
  "button",
734
894
  {
735
895
  type: "button",
736
- className: cx("mk-ms-trigger", open && "open"),
896
+ className: cx("mk-ms-trigger", open && "open", triggerClassName),
737
897
  "aria-haspopup": "listbox",
738
898
  "aria-expanded": open,
739
899
  "aria-label": ariaLabel,
740
900
  title: selected.length > 1
741
- ? selected.map(v => opts.find(o => o.value === v)?.label ?? v).join(", ")
742
- : undefined,
901
+ ? selected.map(v => filterFind(tree, v)?.label ?? v).join(", ")
902
+ : text,
743
903
  onClick: () => setOpen(o => !o),
744
904
  },
745
- h("span", { className: "mk-ms-value" }, dot(single), h("span", { className: "mk-ms-text" }, text)),
905
+ h(
906
+ "span",
907
+ { className: "mk-ms-value" },
908
+ none ? null : dot(single),
909
+ h(
910
+ "span",
911
+ { className: "mk-ms-fit" },
912
+ // The text first: a grid's baseline is its first item's, and the probes are 0 px tall.
913
+ h("span", { key: "text", className: "mk-ms-text" }, text),
914
+ ...sizes.map((t, i) => h("span", { key: i, className: "mk-ms-probe", "aria-hidden": "true" }, t)),
915
+ ),
916
+ ),
746
917
  h(IconChevron, { className: "mk-ms-caret" }),
747
918
  ),
748
919
  open &&
749
920
  h(
750
921
  "div",
751
- {
752
- className: "mk-pop mk-ms-menu",
753
- role: "listbox",
754
- "aria-multiselectable": true,
755
- onClick: cancelLabelActivation,
756
- },
757
- h(
758
- "button",
759
- { type: "button", className: cx("mk-ms-opt", allOn && "active"), "aria-pressed": allOn, onClick: all },
760
- h(Checkbox, { checked: allOn }),
761
- h("span", { className: "mk-ms-label" }, allLabel),
762
- ),
763
- h("div", { className: "mk-ms-sep" }),
764
- ...opts.map(o => {
765
- const on = selected.includes(o.value);
766
- return h(
767
- "div",
768
- {
769
- key: o.value,
770
- role: "option",
771
- "aria-selected": on,
772
- tabIndex: 0,
773
- className: cx("mk-ms-opt", on && "active"),
774
- onClick: () => toggle(o.value),
775
- onKeyDown: e => {
776
- if (e.key === "Enter" || e.key === " ") {
777
- e.preventDefault();
778
- toggle(o.value);
779
- }
780
- },
781
- },
782
- h(Checkbox, { checked: on }),
783
- dot(o),
784
- h("span", { className: "mk-ms-label" }, o.label),
785
- showOnly &&
786
- h(
787
- "button",
788
- {
789
- type: "button",
790
- className: "mk-ms-only",
791
- onClick: e => {
792
- e.stopPropagation();
793
- onChange(multiSelectToggle([], values, o.value, emptyMeansAll));
794
- },
795
- },
796
- "Only",
797
- ),
798
- );
922
+ { className: "mk-pop mk-ms-menu", onClick: cancelLabelActivation },
923
+ h(FilterItems, {
924
+ options: tree,
925
+ value,
926
+ onChange,
927
+ allLabel,
928
+ emptyMeansAll,
929
+ showOnly,
930
+ none,
931
+ onNoneChange: setNone,
932
+ "aria-label": ariaLabel,
799
933
  }),
800
934
  ),
801
935
  );