feat: replace action groups with UI groups

Author: Pluze

+labkit/+ui/+app/create.m

@@ -1,5 +1,5 @@
 function ui = create(spec, varargin)
-%CREATE Build a LabKit UI 3.0 workbench from declarative specs.
+%CREATE Build a LabKit UI 4.0 workbench from declarative specs.
 %
 % App-facing contract:
 %   ui = labkit.ui.app.create(spec, "debug", debugContext)

+labkit/+ui/+app/private/applyCommonValueProps.m

@@ -1,4 +1,4 @@
-% Private UI app helper. Expected caller: UI 3.0 control builders. Inputs are
+% Private UI app helper. Expected caller: UI 4.0 control builders. Inputs are
 % a MATLAB UI handle and validated spec props. Output is none. Side effects
 % assign common value, limit, item, and display-format properties when the
 % target handle supports them.

+labkit/+ui/+app/private/applyTextFit.m

@@ -1,4 +1,4 @@
-% Private UI app helper. Expected caller: UI 3.0 control builders. Inputs are
+% Private UI app helper. Expected caller: UI 4.0 control builders. Inputs are
 % a MATLAB UI text-bearing handle and optional fitting limits. Output is none.
 % Side effects: enables wrapping when supported, reduces font size for long
 % text, and installs a tooltip with the full text when supported.

+labkit/+ui/+app/private/buildControl.m

@@ -13,8 +13,8 @@
                 parentGrid, row);
         case 'action'
             ui = buildAction(ui, controlSpec, parentGrid, row, [1 2]);
-        case 'actionGroup'
-            ui = buildActionGroup(ui, controlSpec, parentGrid, row);
+        case 'group'
+            ui = buildGroup(ui, controlSpec, parentGrid, row, debug);
         case 'filePanel'
             ui = buildFilePanel(ui, controlSpec, parentGrid, row);
         case 'resultTable'
@@ -29,7 +29,7 @@
             ui = buildToolPanelControl(ui, controlSpec, parentGrid, row);
         otherwise
             error('labkit:ui:app:UnsupportedControl', ...
-                'Unsupported UI 3.0 control kind "%s".', controlSpec.kind);
+                'Unsupported UI 4.0 control kind "%s".', controlSpec.kind);
     end
 end
 
@@ -100,7 +100,7 @@
             applyTextFit(control);
         otherwise
             error('labkit:ui:app:UnsupportedFieldKind', ...
-                'Unsupported UI 3.0 field kind "%s".', kind);
+                'Unsupported UI 4.0 field kind "%s".', kind);
     end
     applyCommonValueProps(control, props);
     applySliderTicks(control, props);
@@ -173,10 +173,26 @@ function setRangeValue(newValue)
     end
 end
 
-function ui = buildActionGroup(ui, groupSpec, parentGrid, row)
+function ui = buildGroup(ui, groupSpec, parentGrid, row, debug)
+    if usesActionLayout(groupSpec)
+        ui = buildActionLayout(ui, groupSpec, parentGrid, row);
+        return;
+    end
+    ui = buildFormGroup(ui, groupSpec, parentGrid, row, debug);
+end
+
+function tf = usesActionLayout(groupSpec)
+    layout = lower(char(string(optionValue(groupSpec.props, 'layout', 'auto'))));
+    childKinds = string(cellfun(@(child) child.kind, groupSpec.children, ...
+        'UniformOutput', false));
+    tf = strcmp(layout, 'actions') || ...
+        (strcmp(layout, 'auto') && all(childKinds == "action"));
+end
+
+function ui = buildActionLayout(ui, groupSpec, parentGrid, row)
     actions = groupSpec.children;
     count = max(1, numel(actions));
-    maxColumns = actionGroupMaxColumns(groupSpec);
+    maxColumns = actionLayoutMaxColumns(groupSpec);
     columnCount = min(count, maxColumns);
     rowCount = max(1, ceil(count / columnCount));
     grid = uigridlayout(parentGrid, [rowCount columnCount]);
@@ -187,7 +203,7 @@ function setRangeValue(newValue)
     grid.ColumnWidth = repmat({'1x'}, 1, columnCount);
     grid.Layout.Row = row;
     grid.Layout.Column = [1 2];
-    adapter = baseAdapter(groupSpec, 'actionGroup');
+    adapter = baseAdapter(groupSpec, 'group');
     adapter.grid = grid;
     adapter.actions = struct();
     ui.controls.(groupSpec.id) = adapter;
@@ -204,7 +220,42 @@ function setRangeValue(newValue)
     end
 end
 
-function maxColumns = actionGroupMaxColumns(groupSpec)
+function ui = buildFormGroup(ui, groupSpec, parentGrid, row, debug)
+    childCount = max(1, numel(groupSpec.children));
+    titleText = char(string(optionValue(groupSpec.props, 'title', '')));
+    if strlength(string(titleText)) > 0
+        host = uipanel(parentGrid, 'Title', titleText);
+    else
+        host = uipanel(parentGrid, 'BorderType', 'none');
+    end
+    host.Layout.Row = row;
+    host.Layout.Column = [1 2];
+
+    grid = uigridlayout(host, [childCount 2]);
+    grid.RowHeight = groupRowHeights(groupSpec.children);
+    grid.ColumnWidth = {120, '1x'};
+    grid.RowSpacing = 6;
+    grid.ColumnSpacing = 8;
+    grid.Padding = [0 0 0 0];
+
+    adapter = baseAdapter(groupSpec, 'group');
+    adapter.panel = host;
+    adapter.grid = grid;
+    ui.controls.(groupSpec.id) = adapter;
+    for iChild = 1:numel(groupSpec.children)
+        ui = buildControl(ui, groupSpec.children{iChild}, grid, iChild, debug);
+    end
+end
+
+function rowHeight = groupRowHeights(children)
+    count = max(1, numel(children));
+    rowHeight = repmat({'fit'}, 1, count);
+    for k = 1:numel(children)
+        rowHeight{k} = specRowHeight(children{k}, 'fit');
+    end
+end
+
+function maxColumns = actionLayoutMaxColumns(groupSpec)
     maxColumns = 2;
     labels = actionLabels(groupSpec.children);
     if any(strlength(labels) > 28)

+labkit/+ui/+app/private/createTabbedWorkbenchShell.m

@@ -13,7 +13,7 @@
 %   figPosition - uifigure Position vector.
 %   leftWidth - initial fixed width of the left control panel.
 %   labels - struct with controlsPanel and rightPanel text.
-%   tabSpecs - internal tab specs derived from UI 3.0 app specs.
+%   tabSpecs - internal tab specs derived from UI 4.0 app specs.
 %   rightGridSize - right-side uigridlayout size.
 %   rightRowHeight - right-side grid RowHeight cell array.
 %   rightRowSpacing - right-side grid RowSpacing scalar.
@@ -24,7 +24,7 @@
 %
 % Notes:
 %   Logical tab rows are expanded with physical resize-handle rows here.
-%   App code should use UI 3.0 specs rather than depending on physical row
+%   App code should use UI 4.0 specs rather than depending on physical row
 %   indices.
 
     if nargin < 9

+labkit/+ui/+app/private/runSemanticAppCallback.m

@@ -1,4 +1,4 @@
-% Private UI app helper. Expected caller: UI 3.0 semantic callback wrappers.
+% Private UI app helper. Expected caller: UI 4.0 semantic callback wrappers.
 % Inputs are the current UI registry, control adapter, event payload, app
 % callback, and control id. Side effects: runs the callback in app busy state.
 function runSemanticAppCallback(ui, control, event, appCallback, id)

+labkit/+ui/+app/private/semanticEvent.m

@@ -1,4 +1,4 @@
-% Private UI app helper. Expected callers: UI 3.0 callback wrappers under
+% Private UI app helper. Expected callers: UI 4.0 callback wrappers under
 % +labkit/+ui/+app/private. Inputs are a semantic control adapter, the
 % originating MATLAB UI source/raw event, and a semantic source label. Output is
 % the normalized event payload seen by app callbacks.

+labkit/+ui/+app/private/specRowHeight.m

@@ -1,5 +1,5 @@
 % Private UI app layout helper. Expected caller: buildShellFromSpec and
-% buildSection. Inputs are one validated UI 3.0 spec and an optional default
+% buildSection. Inputs are one validated UI 4.0 spec and an optional default
 % row height. Output is a MATLAB uigridlayout RowHeight value.
 function value = specRowHeight(spec, defaultValue)
     if nargin < 2
@@ -25,8 +25,8 @@
             value = actionHeight(spec);
         case 'resultTable'
             value = tablePanelHeight();
-        case 'actionGroup'
-            value = actionGroupHeight(spec);
+        case 'group'
+            value = groupHeight(spec);
         otherwise
             value = normalizeHeight(defaultValue);
     end
@@ -72,20 +72,54 @@
     value = max(185, 24 * max(1, double(rows)) + 58);
 end
 
-function value = actionGroupHeight(groupSpec)
+function value = groupHeight(groupSpec)
+    if ~usesActionLayout(groupSpec)
+        value = formGroupHeight(groupSpec);
+        return;
+    end
+    value = actionLayoutHeight(groupSpec);
+end
+
+function tf = usesActionLayout(groupSpec)
+    layout = lower(char(string(optionValue(groupSpec.props, 'layout', 'auto'))));
+    childKinds = string(cellfun(@(child) child.kind, groupSpec.children, ...
+        'UniformOutput', false));
+    tf = strcmp(layout, 'actions') || ...
+        (strcmp(layout, 'auto') && all(childKinds == "action"));
+end
+
+function value = actionLayoutHeight(groupSpec)
     count = numel(groupSpec.children);
     if count == 0
         value = defaultControlHeight();
         return;
     end
-    maxColumns = actionGroupMaxColumns(groupSpec);
+    maxColumns = actionLayoutMaxColumns(groupSpec);
     columnCount = min(count, maxColumns);
     rowCount = max(1, ceil(count / columnCount));
     rowHeight = max(defaultControlHeight(), max(actionHeights(groupSpec.children)));
     value = rowCount * rowHeight + ...
         max(0, rowCount - 1) * 6;
 end
 
+function value = formGroupHeight(groupSpec)
+    if isempty(groupSpec.children)
+        value = defaultControlHeight();
+        return;
+    end
+    rowHeights = zeros(1, numel(groupSpec.children));
+    for k = 1:numel(groupSpec.children)
+        childHeight = specRowHeight(groupSpec.children{k}, 'fit');
+        rowHeights(k) = numericRowHeight(childHeight, defaultControlHeight());
+    end
+    titleAllowance = 0;
+    if strlength(string(optionValue(groupSpec.props, 'title', ''))) > 0
+        titleAllowance = 24;
+    end
+    value = sum(rowHeights) + 6 * max(0, numel(rowHeights) - 1) + ...
+        titleAllowance;
+end
+
 function value = fieldHeight(fieldSpec)
     props = fieldSpec.props;
     kind = lower(char(string(optionValue(props, 'kind', 'text'))));
@@ -119,7 +153,7 @@
     value = max(defaultControlHeight(), 20 * lineCount + 6);
 end
 
-function maxColumns = actionGroupMaxColumns(groupSpec)
+function maxColumns = actionLayoutMaxColumns(groupSpec)
     maxColumns = 2;
     labels = actionLabels(groupSpec.children);
     if any(strlength(labels) > 28)

+labkit/+ui/+app/private/validateAppSpec.m

@@ -20,7 +20,7 @@ function validateAppSpec(spec)
     duplicate = firstDuplicate(ids);
     if strlength(duplicate) > 0
         error('labkit:ui:app:DuplicateId', ...
-            'Duplicate UI 3.0 spec id "%s".', char(duplicate));
+            'Duplicate UI 4.0 spec id "%s".', char(duplicate));
     end
     validateTreeShape(spec);
 end
@@ -69,10 +69,13 @@ function validateTreeShape(spec)
         case 'section'
             validateNonEmptySection(spec);
             validateChildKinds(spec, {'field', 'rangeField', 'panner', 'action', ...
-                'actionGroup', 'filePanel', 'resultTable', 'statusPanel', ...
+                'group', 'filePanel', 'resultTable', 'statusPanel', ...
                 'usagePanel', 'logPanel', 'toolPanel'});
-        case 'actionGroup'
-            validateChildKinds(spec, {'action'});
+        case 'group'
+            validateNonEmptyGroup(spec);
+            validateGroupLayout(spec);
+            validateChildKinds(spec, {'field', 'rangeField', 'panner', ...
+                'action', 'group'});
         otherwise
             validateChildKinds(spec, {});
     end
@@ -87,6 +90,36 @@ function validateNonEmptySection(spec)
     end
 end
 
+function validateNonEmptyGroup(spec)
+    if isempty(spec.children)
+        error('labkit:ui:app:EmptyGroup', ...
+            'Spec "%s" declares an empty group. Add semantic child controls.', ...
+            spec.id);
+    end
+end
+
+function validateGroupLayout(spec)
+    layout = string(optionValue(spec.props, 'layout', 'auto'));
+    allowed = ["auto", "actions", "form", "inline", "grid"];
+    if ~isscalar(layout) || ~any(layout == allowed)
+        error('labkit:ui:app:InvalidGroupLayout', ...
+            'Spec "%s" uses unsupported group layout "%s".', ...
+            spec.id, char(layout));
+    end
+    if layout == "actions" && ~allGroupChildrenAre(spec, 'action')
+        error('labkit:ui:app:InvalidGroupLayout', ...
+            'Spec "%s" uses action layout but contains non-action children.', ...
+            spec.id);
+    end
+end
+
+function tf = allGroupChildrenAre(spec, kind)
+    tf = true;
+    for k = 1:numel(spec.children)
+        tf = tf && strcmp(spec.children{k}.kind, kind);
+    end
+end
+
 function validateNoAppLayoutProps(spec)
     layoutProps = {'height', 'minRows', 'minHeight', 'maxColumns', ...
         'rowSpacing', 'columnSpacing', 'padding', 'chrome', ...
@@ -127,6 +160,13 @@ function assertCommonSpec(spec)
             ~iscell(spec.children) || ...
             ~(isempty(spec.children) || isrow(spec.children))
         error('labkit:ui:app:InvalidSpec', ...
-            'UI 3.0 specs must be scalar structs with cell row children.');
+            'UI 4.0 specs must be scalar structs with cell row children.');
+    end
+end
+
+function value = optionValue(opts, name, defaultValue)
+    value = defaultValue;
+    if isstruct(opts) && isfield(opts, name)
+        value = opts.(name);
     end
 end