@flusys/ng-shared 9.1.0 → 9.1.2

package/README.md

@@ -183,14 +183,25 @@ All three guards redirect to `/` by default. Pass a second argument to change it
 
 ```html
 <lib-action-select inputId="permission" [(value)]="permissionCode" [placeholder]="defaultCode" />
-<lib-action-multi-select inputId="actionGroups" [(value)]="actionGroups" />
+<lib-action-multi-select inputId="codes" [(value)]="codes" />
 ```
 
-- Lists actions from the optional `ACTION_PROVIDER` token (`IActionProvider.getActions()` → flat `IActionBasicInfo[]` with `parentId` / `serial`); `provideIamProviders()` from `@flusys/ng-iam` wires it.
+- Lists actions from the optional `ACTION_PROVIDER` token (`IActionProvider.getActions(scope)` → flat `IActionBasicInfo[]` with `parentId` / `serial`); `provideIamProviders()` from `@flusys/ng-iam` wires it.
+- `scope` input (`ActionScope`): `'company'` (default) lists the caller's company whitelist (`/actions/tree-for-permission`), for assigning access; `'all'` lists the whole active action tree (`/actions/tree`), for designers that define what a feature checks (ng-entity-builder) - their own provisioned actions are not whitelisted to any company.
 - Both render an `f-treeselect` of the action hierarchy, ordered by `serial` then name. Actions without a `code` are groups: they expand but can't be picked, and a group with nothing pickable under it is hidden. The multi picker uses checkboxes that do not cascade, so ticking a node picks only that code. Search matches name or code.
 - Without a provider (IAM not installed) they fall back to typing codes: a text input, or chips added with Enter for the multi picker.
 - A saved code that is not an action stays selectable, so older or default codes still show.
 
+### Permission rules (`<lib-permission-logic>`)
+
+For an AND / OR rule rather than a flat list, `<lib-permission-logic>` edits an `IGroupNode` (`ILogicNode` tree): an *Any of these (OR)* / *All of these (AND)* group whose rows are `<lib-action-select>` permissions or nested groups (up to `MAX_PERMISSION_LOGIC_DEPTH` = 5 levels, the server's limit; a new group takes the other operator). `scope` is passed down to every row.
+
+```html
+<lib-permission-logic scope="company" [group]="group()" (groupChange)="onChange($event)" />
+```
+
+Helpers from the same file: `asPermissionGroup(logic)` (a stored rule, a single action or nothing as the group the editor takes), `isEmptyPermissionLogic(logic)` (store `null` instead of an empty group), `hasIncompletePermission(logic)` (an empty row or group, to block saving), `emptyPermissionGroup(operator)`. Used by ng-form-builder (`scope="company"`, form access) and ng-entity-builder (`scope="all"`, flow access and Check permission steps).
+
 ---
 
 ## 6. TranslatePipe
@@ -201,6 +212,24 @@ All three guards redirect to `/` by default. Pass a second argument to change it
 
 The pipe also accepts a backend message reference (`IMessageRef`: `{ messageKey, messageVariables? }`), e.g. `{{ plan.warnings[0] | translate }}`. `TranslateService.translateRef(ref)` does the same in code and translates variables that are themselves references first. `errorToMessageRef(error, fallbackKey?)` (`@flusys/ng-shared`) turns a failed HTTP call into a reference from the response's `messageKey`/`messageVariables`.
 
+## 7. Branch Hierarchy Helpers
+
+Pure functions over a flat branch list (`{ id, name, parentId?, serial?, displayParentId? }`), exported from `@flusys/ng-shared`. A branch hangs under `displayParentId` when the list carries it (`null` = no granted ancestor, a root), else under `parentId` - the backend sends `displayParentId` (nearest granted ancestor) with lists of granted branches, so the tree keeps its shape when a branch in between is not granted. Every one tolerates bad data: a repeated id keeps its first entry, empty ids are ignored, a branch with no listed ancestor (or only itself) is a root, and a parent cycle never loops or hides a branch.
+
+| Function | Returns |
+| --- | --- |
+| `buildBranchHierarchy(branches)` | sorted tree of `{ data, depth, children }` (siblings by `serial`, then name); a cycle is cut at one branch, which becomes a root |
+| `filterBranchHierarchy(items, match, { includeDescendants? })` | matches plus every branch above them (a search never shows a branch without its path) |
+| `buildBranchTreeNodes(branches, excludeIds?)` | `TreeNode[]` for `f-treeselect`; `excludeIds` drops those branches and everything under them |
+| `flattenBranchTree(branches)` | display-order rows `{ branch, depth, hasChildren }` for indented lists |
+| `collectBranchDescendantIds(branches, ids, { includeSelf?, maxDepth? })` | every branch under `ids`, level by level - e.g. a branch filter that also matches sub-branches |
+| `collectBranchAncestorIds(branches, id, { includeSelf?, maxDepth? })` | parent chain, nearest first, stopping at a missing parent |
+| `isBranchWithin(branches, id, ancestorId)` | `id` is `ancestorId` or anywhere under it |
+| `getBranchPath(branches, id)` | branches from the top-most known ancestor down to `id` (breadcrumbs, "HQ / East") |
+| `normalizeBranchIds(ids)` / `compareBranches(a, b)` | each id once without empties / the sibling sort order |
+
+`maxDepth: 1` means direct children or the direct parent only. Every branch dropdown uses `buildBranchTreeNodes`: the ng-auth login selection and branch form, the ng-layout topbar switcher, and the ng-iam user role/action selectors. The ng-auth Manage Branch Permissions dialog uses `flattenBranchTree` and `getBranchPath`. `IUserBranchPermission` carries optional `parentId`/`serial`. The backend twin of these helpers lives in `@flusys/nestjs-shared/utils`.
+
 ## License
 
 MIT © FLUSYS