@wildo-ai/framework-knowledge 1.1.12 → 1.1.13
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/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +10 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +8 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +5 -2
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +9 -0
- package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -1
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +14 -0
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +1 -1
- package/dist/knowledge/references/application-maturity.config.md +43 -0
- package/dist/knowledge/references/example.infra.environment-config.local.md +2 -2
- package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +21 -0
- package/dist/knowledge/references/platform.config.infrastructure-host.md +1 -0
- package/dist/knowledge/references/platform.config.platform-key-management.md +5 -2
- package/dist/knowledge/references/requirements.engine-substance.md +38 -0
- package/dist/knowledge/references/requirements.functional-requirement.config.md +11 -0
- package/dist/knowledge/references/requirements.non-functional-requirement.config.md +11 -0
- package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +20 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +72 -0
- package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +3 -3
- package/dist/knowledge/references/saas.frontend.chart-dashboard.md +38 -35
- package/dist/knowledge/references/saas.models.chart-dashboard-tile-sizes.md +40 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails-environment.md +52 -0
- package/dist/knowledge/references/saas.models.organization-dashboard-layout.md +61 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +41 -1
- package/dist/knowledge/registries/playbooks.json +1 -1
- package/dist/knowledge/registries/source-tags.json +1052 -982
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +11 -0
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +43 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +20 -3
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +12 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +16 -4
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +144 -6
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +72 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +12 -2
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +12 -2
- package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -1
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -2
- package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +13 -0
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +26 -2
- package/dist/knowledge/skills/infra-environment-config/references/framework-agent-content-guardrails-environment-api.md +67 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +1 -0
- package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +5 -2
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +17 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +2 -1
- package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +21 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +166 -39
- package/dist/knowledge/topic-index.json +197 -58
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Framework API: `agentContentGuardrails` (an environment without a content classifier)
|
|
2
|
+
|
|
3
|
+
The source contract for what ONE environment does with its agents' classifier-backed content guardrails
|
|
4
|
+
(`contentGuardrails.promptInjection`, `contentGuardrails.outputModeration`) where no classifier is present for them: it
|
|
5
|
+
declares no provider for `EngineCapability.AI_CONTENT_SAFETY`, the one it selects does not offer the guardrail, or that
|
|
6
|
+
one's credentials are not authored in this environment's `secrets.json → providerEnv`.
|
|
7
|
+
|
|
8
|
+
Read this when:
|
|
9
|
+
|
|
10
|
+
- an agent refuses every turn in staging or production because no classifier is present for its guardrail there (often:
|
|
11
|
+
that environment has no key for it), and running it unguarded there is the decision;
|
|
12
|
+
- `wildo context launch-blockers` lists an environment whose agents run unguarded;
|
|
13
|
+
- the backend's startup log says an agent `RUNS UNGUARDED`.
|
|
14
|
+
|
|
15
|
+
## Import Origins
|
|
16
|
+
|
|
17
|
+
- `@wildo-ai/saas-models`
|
|
18
|
+
|
|
19
|
+
## Source Excerpts
|
|
20
|
+
|
|
21
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
*
|
|
25
|
+
* What an environment does with an agent's classifier-backed content guardrails (`contentGuardrails.promptInjection`,
|
|
26
|
+
* `contentGuardrails.outputModeration`) when NO classifier for the guardrail is present there: its configuration declares
|
|
27
|
+
* no provider for `EngineCapability.AI_CONTENT_SAFETY`, the provider it selects does not offer that guardrail, or that
|
|
28
|
+
* provider's credentials are not authored in this environment's `secrets.json → providerEnv`. Imported
|
|
29
|
+
* from `@wildo-ai/saas-models`; authored as `agentContentGuardrails` in `infrastructure/<env>/wildo.infra.<env>.config.ts`.
|
|
30
|
+
*/
|
|
31
|
+
export enum AgentContentGuardrailsWithoutClassifier {
|
|
32
|
+
/** The default, and what an environment that authors nothing gets: the agent refuses every turn. */
|
|
33
|
+
REFUSE = 'refuse',
|
|
34
|
+
/**
|
|
35
|
+
* The agent runs without each guardrail no classifier is present for here (its tool results unscreened, or its output
|
|
36
|
+
* unmoderated). A classifier that is there and cannot be used is never waived: a declared provider that did not load or
|
|
37
|
+
* a category it does not assess still refuses the turn, and a key that is set and refused, or an outage, still
|
|
38
|
+
* withholds the output. Named at startup, and listed by launch-blockers outside a local environment.
|
|
39
|
+
*/
|
|
40
|
+
RUN_UNGUARDED = 'run_unguarded',
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The environment's declaration. `reason` is required with `RUN_UNGUARDED`: it is printed beside every agent the backend
|
|
45
|
+
* leaves unguarded, so the next reader knows it was decided, and by whom or why.
|
|
46
|
+
*
|
|
47
|
+
* ```ts
|
|
48
|
+
* agentContentGuardrails: {
|
|
49
|
+
* withoutClassifier: AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED,
|
|
50
|
+
* reason: 'Staging has no Azure Content Safety key; production authors one.',
|
|
51
|
+
* },
|
|
52
|
+
* ```
|
|
53
|
+
*/
|
|
54
|
+
export const EnvironmentAgentContentGuardrailsSchema = z.discriminatedUnion('withoutClassifier', [
|
|
55
|
+
z.strictObject({
|
|
56
|
+
withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.REFUSE),
|
|
57
|
+
}),
|
|
58
|
+
z.strictObject({
|
|
59
|
+
withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED),
|
|
60
|
+
reason: z.string().trim().min(10, 'Say why this environment runs its agents unguarded (at least 10 characters).').max(500),
|
|
61
|
+
}),
|
|
62
|
+
]);
|
|
63
|
+
export type EnvironmentAgentContentGuardrails = z.output<typeof EnvironmentAgentContentGuardrailsSchema>;
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Authored in `infrastructure/<env>/wildo.infra.<env>.config.ts`, projected by `wildo config sync` to the application
|
|
67
|
+
backend and workers as `WILDO_AGENT_CONTENT_GUARDRAILS`. Absent means `REFUSE`.
|
|
@@ -84,6 +84,7 @@ export const WildoHostedInfraEnvConfigSchema = z.strictObject({
|
|
|
84
84
|
providerSelection: WILDO_INFRA_ENV_CONFIG_SHAPE.providerSelection,
|
|
85
85
|
providerConfigurations: WILDO_INFRA_ENV_CONFIG_SHAPE.providerConfigurations,
|
|
86
86
|
email: WILDO_INFRA_ENV_CONFIG_SHAPE.email,
|
|
87
|
+
agentContentGuardrails: WILDO_INFRA_ENV_CONFIG_SHAPE.agentContentGuardrails,
|
|
87
88
|
ownershipDnsStandIn: WILDO_INFRA_ENV_CONFIG_SHAPE.ownershipDnsStandIn,
|
|
88
89
|
systemsOfRecord: WILDO_INFRA_ENV_CONFIG_SHAPE.systemsOfRecord,
|
|
89
90
|
documentationSite: WILDO_INFRA_ENV_CONFIG_SHAPE.documentationSite,
|
|
@@ -83,11 +83,14 @@ cloud account for it.
|
|
|
83
83
|
* - Azure Key Vault (a vault in the Azure RBAC permission model): two user-assigned managed identities on apps-manager,
|
|
84
84
|
* each with a CUSTOM role on the vault. The built-in roles do not fit: "Key Vault Crypto User" can update and back up a
|
|
85
85
|
* key, and "Key Vault Crypto Officer" holds `vaults/keys/*`, signing included.
|
|
86
|
-
* - Signer: `Microsoft.KeyVault/vaults/keys/read`, `…/keys/
|
|
86
|
+
* - Signer: `Microsoft.KeyVault/vaults/keys/read`, `…/keys/sign/action`,
|
|
87
87
|
* `…/keys/encrypt/action`, `…/keys/decrypt/action` (a data key is wrapped with A256GCM under an `oct-HSM` key, which
|
|
88
88
|
* a Premium vault offers in preview; a Standard vault cannot hold one and serves signing only).
|
|
89
|
-
* - Operator: `…/keys/read`, `…/keys/
|
|
89
|
+
* - Operator: `…/keys/read`, `…/keys/create/action`, `…/keys/update/action` (disable),
|
|
90
90
|
* `…/keys/delete`, `…/keys/purge/action`.
|
|
91
|
+
* Azure has no `keys/versions/read` data action: `keys/read` reads every version. Measured 2026-11-12 (#3697) with two
|
|
92
|
+
* user-assigned managed identities holding exactly these roles: each verb succeeded as its own identity and answered
|
|
93
|
+
* 403 as the other one.
|
|
91
94
|
* The vault's recovery level decides whether a destroyed key is purged at once or kept until retention ends.
|
|
92
95
|
* - Azure Managed HSM (`*.managedhsm.azure.net`): the same two identities, with custom roles in the HSM's LOCAL RBAC
|
|
93
96
|
* (the built-in "Managed HSM Crypto User" can sign and back up, and cannot purge). Signer:
|
|
@@ -142,9 +142,9 @@ erasure calls. An entry that lists nothing is used for nothing.
|
|
|
142
142
|
**A content-safety classifier in the `companion` scope screens what your
|
|
143
143
|
coding agents read.** While the companion builds the application, a coding
|
|
144
144
|
agent's brief can carry text written outside the repository: market and
|
|
145
|
-
regulatory material a research step gathered from the web. Scope
|
|
146
|
-
|
|
147
|
-
|
|
145
|
+
regulatory material a research step gathered from the web. Scope a classifier
|
|
146
|
+
that SCREENS (`azure-content-safety`; `openai-moderation` moderates output
|
|
147
|
+
only and cannot serve here) under `providers.scopes.companion` with
|
|
148
148
|
`engineCapabilities: [EngineCapability.AI_CONTENT_SAFETY]`, enable
|
|
149
149
|
`AI_CONTENT_SAFETY` in `engineCapabilities`, and set its key with
|
|
150
150
|
`wildo secrets set`. The companion then screens each such element before
|
|
@@ -310,6 +310,20 @@ rather than an API key (Google Vertex AI) declares two more fields:
|
|
|
310
310
|
secrets contract declares, admitted only as an identifier (letters, digits,
|
|
311
311
|
`.`, `_`, `-`), and handed to `sdkFactory` as `context.deploymentParameters`.
|
|
312
312
|
|
|
313
|
+
An LLM or embeddings arm whose vendor authenticates by SIGNING each request
|
|
314
|
+
with IAM credentials (Amazon Bedrock with AWS SigV4) declares `requestSigning`
|
|
315
|
+
INSTEAD of `apiKey`, exactly one of the two:
|
|
316
|
+
|
|
317
|
+
- `requestSigning: { scheme: ProviderRestSigningScheme.AWS_SIGV4, keyIdSecretRef, secretKeySecretRef, sessionTokenSecretRef? }`
|
|
318
|
+
— each a slot your secrets contract declares (the session token only for
|
|
319
|
+
temporary credentials, `required: false`). The engine reads them and calls
|
|
320
|
+
your `sdkFactory` with an empty first argument and the credentials in
|
|
321
|
+
`context.requestSigningCredentials` (`keyId`, `secretKey`, `sessionToken?`,
|
|
322
|
+
`region?`). Pass every value to your SDK client explicitly, so it reads none
|
|
323
|
+
of the process's `AWS_*` variables, and sign for the Region of the host you
|
|
324
|
+
call. A service account cannot sit beside it, and a module declaring both,
|
|
325
|
+
neither, or an undeclared slot is refused at startup.
|
|
326
|
+
|
|
313
327
|
This covers the API calls only. When the same slot also fills an OAuth2
|
|
314
328
|
endpoint host (Workday's `WORKDAY_API_HOST` names its token endpoint too),
|
|
315
329
|
the connect flow refuses a loopback host in every environment, because that
|
package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md
CHANGED
|
@@ -55,8 +55,9 @@ operations to a reviewer in these terms rather than as "always audited":
|
|
|
55
55
|
| A **transactional** operation of your application, called at the top level: one with a `transactionalCore` implementation, a bulk write (`updateMany`, `deleteMany`, …), a token-issuing, token-consuming or token-revoking operation, a create that numbers a document, or a write to an outbound pipeline's destination | **Durable.** The prepared row is kept in the framework's post-commit effect outbox inside the operation's own transaction (with the notifications that go with it) and written right after the commit from there. If the process ends between the commit and the write, the framework's outbox relay writes it later (once at the next startup, then every five minutes), under the id it was prepared with, once. A write that rolls back keeps nothing. Every audited write nested inside that transaction is covered too. One exception: when an effect of that transaction cannot be kept (retiring a SIEM destination, a generated secret), the whole operation is best effort, as the last row describes. |
|
|
56
56
|
| A verb a framework sweep dispatches (the expiry of organization relationships, professional qualifications and access grants, the lifting of a suspension, an invitation's revocation, a tenant's purge) | **Durable**, the same way, settled by that sweep's next run rather than by the relay, also when someone calls the verb directly. For the purge and the invitation sweep that run is daily, so after a crash such a row can take up to a day to appear. |
|
|
57
57
|
| A **plain audited create, update or delete with no custom implementation, or whose every custom implementation declares `hookTransactionPosture: RUNS_INSIDE_TRANSACTION`**, reached through the framework (`API_CALL`, `INTERNAL_CALL`), audited by its declaration (its `riskLevel` is HIGH or CRITICAL, or it sets `auditableEvent.auditBelowRiskFloor`): a single-row `create`, `update` or `delete`, or a custom operation that behaves as one, including one gated by an `enabledCondition` | **Durable**, the same way as a transactional operation: the framework opens a transaction around the write for the sake of its audit row, so the row is kept in the outbox and the relay writes it after a crash. Nothing else changes, because nothing but the framework's own core runs inside that transaction: a delete's cascade already ran in a transaction of its own, removes its children through their repositories, and leaves a file's stored object to the files cleanup batch. A declared implementation's hooks run inside it too, which is why they must do nothing outside the database before the commit (`backend-custom-operation`, `references/framework-hook-transaction-posture-api.md`). A lost race on an `enabledCondition` still answers `409 version_conflict`: the row is re-read in the transaction, and a row that moved since the request was admitted is refused. |
|
|
58
|
+
| A **multi-row** `updateMany` / `deleteMany` with no custom implementation and the default response, reached through the framework (`API_CALL`, `INTERNAL_CALL`) and audited by its declaration | **Durable, one chunk at a time.** One transaction holds at most 100 rows (the bound a bulk request already has). A selection within it runs as one transaction, like a single-row write. A larger one runs as consecutive chunks of at most 100 rows, each its own transaction with its own audit row naming its rows: an id list is cut into slices, a filter is walked by `_id`, and your filter still applies to every chunk. So such a write is no longer one atomic statement: when a chunk fails, the chunks before it stay committed and recorded, and the error reaches your code. A custom operation that borrows a multi-row verb and writes the rows itself joins when its implementation declares `maximumRowsWrittenPerAttempt` (at most 100) beside `RUNS_INSIDE_TRANSACTION`; one whose hook selects an unbounded population stays best effort. |
|
|
58
59
|
| An engine writer that owns its outbox (`IMPLEMENTATION_OUTBOX`, billing's subscription mutations) | **Durable**, through that writer's own outbox and relay. Reserved for engine writers: an application cannot declare it. |
|
|
59
|
-
| Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row write
|
|
60
|
+
| Any other audited write called at the top level: a plain create, update or delete with a custom implementation that does not declare `RUNS_INSIDE_TRANSACTION` (undeclared, or `STAYS_OUTSIDE_TRANSACTION` because a hook's answer depends on a provider call or an audit row that must exist first), a multi-row `createMany`, a multi-row write whose implementation selects its own rows without declaring how many one attempt writes, a scheduled (`CRON_JOB`, `BATCH_JOB`) variant, a write audited only because of who performed it (a decided agent proposal, a representative), a write inside a transaction your code opened itself rather than an operation's, and an `OVERRIDE_ALL` implementation | **Best effort.** The row is written right after the commit. A store that refuses the write is logged and counted (`audit_store_failure_total`). A process that ends between the commit and the write loses the row, and nothing counts that loss. When its row must survive a crash, keep the hooks inside the database and declare `RUNS_INSIDE_TRANSACTION`, or give the operation a `transactionalCore` implementation (its hooks then run inside the transaction either way, so keep provider calls out of them). |
|
|
60
61
|
|
|
61
62
|
The durable rows need the outbox in the same database as the operation, which is always the case in an application (it
|
|
62
63
|
uses one transactional store). A process where it is not says so at startup, per resource.
|
|
@@ -102,6 +102,27 @@ type OrganizationEscalationPolicies_CoreOperations =
|
|
|
102
102
|
*/
|
|
103
103
|
dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },
|
|
104
104
|
|
|
105
|
+
/**
|
|
106
|
+
* On a person's Art. 15 export graph: a policy names the person it escalates to (`targetUserId`) and whoever created it
|
|
107
|
+
* (`createdByUserId`), and both foreign keys put it there. Being named as an escalation target, or as a policy's author,
|
|
108
|
+
* is information about that person, so the rows are disclosed, as the module's other member-naming resources are. Until
|
|
109
|
+
* this was declared, the fail-closed export refused every access request of a person this resource can name (the
|
|
110
|
+
* account-erasure-journey lane's download answered 500, #3743).
|
|
111
|
+
*/
|
|
112
|
+
systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
|
|
113
|
+
/**
|
|
114
|
+
* Withheld from every copy: the organization's endpoint, not the person's data, and a webhook URL often carries the
|
|
115
|
+
* credential that authorizes posting to it.
|
|
116
|
+
*/
|
|
117
|
+
subjectExportOthersDataFields: ['webhookUrl'],
|
|
118
|
+
/**
|
|
119
|
+
* Each person's copy withholds the OTHER person the row names: the target's copy does not say who configured the
|
|
120
|
+
* policy, and the author's copy does not say whom it escalates to. An actor's identity is that actor's data.
|
|
121
|
+
*
|
|
122
|
+
* spec-cite: GDPR Art. 15(4) (https://gdpr-info.eu/art-15-gdpr/), as `organizationRepresentativeAssignments` cites it
|
|
123
|
+
*/
|
|
124
|
+
subjectExportOthersDataFieldsByForeignKey: { targetUserId: ['createdByUserId'], createdByUserId: ['targetUserId'] },
|
|
125
|
+
|
|
105
126
|
coreOperations: [
|
|
106
127
|
CoreResourceOperation.READ,
|
|
107
128
|
CoreResourceOperation.LIST,
|
|
@@ -260,7 +260,7 @@ What is **not** in either block (and shouldn't be):
|
|
|
260
260
|
- `references/composite-embedding-checklist.md`
|
|
261
261
|
- `references/framework-composite-view-contracts-api.md` — source-backed composite view types & `defineCompositeView`
|
|
262
262
|
- `references/framework-inserted-view-identity-api.md` — source-backed inserted-view refs for embedded surfaces
|
|
263
|
-
- `references/framework-chart-dashboard-api.md` — source-backed `ChartDashboard` tiles and `defineChartDashboardView`: charts of several resources on one responsive grid (column cap, two-column and two-row tiles), each tile hidden from a viewer the chart's backend gate would refuse
|
|
263
|
+
- `references/framework-chart-dashboard-api.md` — source-backed `ChartDashboard` tiles and `defineChartDashboardView`: charts of several resources on one responsive grid (column cap, two-column and two-row tiles), each tile hidden from a viewer the chart's backend gate would refuse; with a `layoutRef`, an organization's administrators reorder, resize and hide its tiles for their members
|
|
264
264
|
|
|
265
265
|
## Verification
|
|
266
266
|
|
package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md
CHANGED
|
@@ -30,6 +30,9 @@ declares. Read this when you need to:
|
|
|
30
30
|
container, for a dashboard that shares its row with something else (a block of counters, a list);
|
|
31
31
|
`TWO` stops at two. A span applies only where the grid has that many columns, so a narrow pane
|
|
32
32
|
still stacks every tile.
|
|
33
|
+
- `ChartDashboardTileSpan` and `ChartDashboardTileRows` are imported from `@wildo-ai/saas-models` (the
|
|
34
|
+
stored layout below shares them); `ChartDashboard`, `ChartDashboardColumns` and `ChartDashboardTile` from
|
|
35
|
+
`@wildo-ai/saas-frontend-lib`.
|
|
33
36
|
- `rows: ChartDashboardTileRows.TWO` makes a tile two rows tall: a large chart beside two small ones
|
|
34
37
|
stacked. Order the tiles `[small, large, small]` so the second small one flows into the row under
|
|
35
38
|
the first. Give each tile the canvas `height` that fills its cell (a two-row tile is roughly two
|
|
@@ -62,11 +65,33 @@ type with no dimension. The backend also refuses, at startup, a computed measure
|
|
|
62
65
|
parse, calls a function the engine does not provide, or reads a name that is not a measure, a dimension or an
|
|
63
66
|
earlier computed measure listed in its `dependsOn`.
|
|
64
67
|
|
|
68
|
+
## Letting each organization arrange it
|
|
69
|
+
|
|
70
|
+
Give the dashboard a `layoutRef` (a name unique within the application, e.g. `'operations-dashboard'`)
|
|
71
|
+
and each organization may arrange it for its own members:
|
|
72
|
+
|
|
73
|
+
- An organization administrator (the roles of `ORGANIZATION_DASHBOARD_LAYOUT_EDITOR_ROLES`, `ORG_ADMIN`)
|
|
74
|
+
sees a "customize" button above the grid. It opens the layout editor: move tiles up and down, set each
|
|
75
|
+
one's width and height, hide or show it, save, or reset to the declared layout.
|
|
76
|
+
- The arrangement is stored as the organization's `organizationDashboardLayouts` row for that ref (one
|
|
77
|
+
per organization and dashboard). Every member reads it; only administrators write it, and every write is
|
|
78
|
+
audited with the tiles before and after.
|
|
79
|
+
- The arrangement only ARRANGES the tiles you declare. An entry naming a tile you no longer declare is
|
|
80
|
+
ignored, and a tile you add later is shown after the stored ones until an administrator places it. It
|
|
81
|
+
never shows a chart to someone who may not read it: the gate runs after it.
|
|
82
|
+
- Without a `layoutRef` the dashboard is always laid out as declared, and nothing is read.
|
|
83
|
+
- Two dashboards on one page take two refs: each is arranged on its own.
|
|
84
|
+
- The editor's words are the `HIGH_LEVEL_VIEWS_CHART_DASHBOARD_LAYOUT_EDITOR` component labels; the tile
|
|
85
|
+
names are the chart views' own titles.
|
|
86
|
+
|
|
87
|
+
The table is an engine resource, so a PostgreSQL application owes a migration creating it (`wildo db
|
|
88
|
+
generate`), like any resource the engine adds.
|
|
89
|
+
|
|
65
90
|
## Two ways to place it
|
|
66
91
|
|
|
67
92
|
- Inside a composite you write: `<ChartDashboard tiles={[…]} />` in a `<Section>` of your
|
|
68
93
|
`CompositeLayout`, beside the composite's other content.
|
|
69
|
-
- As the whole view: `defineChartDashboardView({ tiles: […], …composite config })` in the frontend
|
|
94
|
+
- As the whole view: `defineChartDashboardView({ tiles: […], columns?, layoutRef?, …composite config })` in the frontend
|
|
70
95
|
module's `compositeViews` map. The rest of the config (`icon`, `sectionRefs`,
|
|
71
96
|
`requiredFeatures`) is the composite view's own.
|
|
72
97
|
|
|
@@ -81,27 +106,6 @@ earlier computed measure listed in its `dependsOn`.
|
|
|
81
106
|
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
82
107
|
|
|
83
108
|
```tsx
|
|
84
|
-
/** How many grid columns a dashboard tile spans, where the dashboard is wide enough to have them. */
|
|
85
|
-
export enum ChartDashboardTileSpan {
|
|
86
|
-
/** One column (the default): a donut, a bar of a few categories. */
|
|
87
|
-
ONE = 'one',
|
|
88
|
-
/** Two columns: a trend over time, a bar of many categories. One column where the dashboard has one. */
|
|
89
|
-
TWO = 'two',
|
|
90
|
-
/** The whole row: a long timeline, a wide table-like chart. */
|
|
91
|
-
FULL = 'full',
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
/** How many grid rows a dashboard tile spans, where the dashboard has more than one column. */
|
|
95
|
-
export enum ChartDashboardTileRows {
|
|
96
|
-
/** One row (the default). */
|
|
97
|
-
ONE = 'one',
|
|
98
|
-
/**
|
|
99
|
-
* Two rows: a large chart beside two smaller ones stacked in the next column. Place it right after the first
|
|
100
|
-
* small tile, so the second small tile flows into the row beneath the first: `[small, large (TWO rows), small]`.
|
|
101
|
-
*/
|
|
102
|
-
TWO = 'two',
|
|
103
|
-
}
|
|
104
|
-
|
|
105
109
|
/**
|
|
106
110
|
* The most columns a dashboard's grid reaches, as its container widens. Every dashboard is one column in a narrow pane.
|
|
107
111
|
*/
|
|
@@ -126,13 +130,15 @@ export interface ChartDashboardTile {
|
|
|
126
130
|
resourceType: string;
|
|
127
131
|
/** The chart view's `ref` on that resource (`InsertedChartDeclaration.ref`, usually `<chartDefinition>.ref`). */
|
|
128
132
|
chartViewRef: string;
|
|
129
|
-
/** Grid columns the tile spans. Default:
|
|
133
|
+
/** Grid columns the tile spans (`ChartDashboardTileSpan`, `@wildo-ai/saas-models`). Default: `ONE`. */
|
|
130
134
|
span?: ChartDashboardTileSpan;
|
|
131
|
-
/** Grid rows the tile spans. Default:
|
|
135
|
+
/** Grid rows the tile spans (`ChartDashboardTileRows`, `@wildo-ai/saas-models`). Default: `ONE`. */
|
|
132
136
|
rows?: ChartDashboardTileRows;
|
|
133
137
|
/**
|
|
134
|
-
* Chart canvas height in px (the canvas is sized by this, not by the tile). Default:
|
|
135
|
-
*
|
|
138
|
+
* Chart canvas height in px for the tile's declared `rows` (the canvas is sized by this, not by the tile). Default:
|
|
139
|
+
* 280 for a one-row chart, 592 for a two-row one (two rows and the gap between them); a KPI tile takes the height of its
|
|
140
|
+
* figure, and this only sizes its loading placeholder (default 64). When an organization's layout changes the tile's
|
|
141
|
+
* rows, this height is doubled (plus the gap) or halved with them.
|
|
136
142
|
*/
|
|
137
143
|
height?: number;
|
|
138
144
|
}
|
|
@@ -142,6 +148,13 @@ export interface ChartDashboardProps {
|
|
|
142
148
|
tiles: readonly ChartDashboardTile[];
|
|
143
149
|
/** The most columns the grid reaches. Default: {@link ChartDashboardColumns.FOUR}. */
|
|
144
150
|
columns?: ChartDashboardColumns;
|
|
151
|
+
/**
|
|
152
|
+
* The dashboard's name for an organization's stored arrangement of it (`organizationDashboardLayouts.dashboardRef`),
|
|
153
|
+
* unique within the application, e.g. `'home-analytics'`. Given one, the organization's administrators may reorder,
|
|
154
|
+
* resize and hide its tiles for every member, and go back to the declared layout; without one the dashboard is always
|
|
155
|
+
* laid out as declared.
|
|
156
|
+
*/
|
|
157
|
+
layoutRef?: string;
|
|
145
158
|
className?: string;
|
|
146
159
|
}
|
|
147
160
|
|
|
@@ -159,6 +172,11 @@ export interface ChartDashboardProps {
|
|
|
159
172
|
*
|
|
160
173
|
* A KPI tile (a chart view whose chart is `ChartType.KPI`) shows one figure under that title, hidden by the same rule.
|
|
161
174
|
*
|
|
175
|
+
* With a `layoutRef`, the current organization's stored arrangement applies first (order, sizes, hidden tiles); the read
|
|
176
|
+
* gate then applies to what is left. An administrator who may arrange it gets a "customize" button above the grid,
|
|
177
|
+
* opening the layout editor, and keeps it even when every tile is hidden. The grid waits for the arrangement to be read,
|
|
178
|
+
* and a read that fails shows the declared layout.
|
|
179
|
+
*
|
|
162
180
|
* Place it inside a composite view (`CompositeLayout`), or declare a whole view as one with
|
|
163
181
|
* {@link defineChartDashboardView}.
|
|
164
182
|
*
|
|
@@ -173,29 +191,39 @@ export interface ChartDashboardProps {
|
|
|
173
191
|
* />
|
|
174
192
|
* ```
|
|
175
193
|
*/
|
|
176
|
-
export function ChartDashboard({ tiles, columns = ChartDashboardColumns.FOUR, className }: ChartDashboardProps): React.JSX.Element | null {
|
|
194
|
+
export function ChartDashboard({ tiles, columns = ChartDashboardColumns.FOUR, layoutRef, className }: ChartDashboardProps): React.JSX.Element | null {
|
|
177
195
|
const { registry } = useResourceRegistry();
|
|
178
196
|
const viewer = useViewerEffectiveRoles();
|
|
197
|
+
const layout = useChartDashboardLayout(layoutRef, viewer);
|
|
198
|
+
const arrangedTiles = useMemo(
|
|
199
|
+
() => arrangeChartDashboardTiles(tiles, layout.stored?.tiles).filter((entry) => !entry.hidden).map((entry) => entry.tile),
|
|
200
|
+
[tiles, layout.stored],
|
|
201
|
+
);
|
|
179
202
|
const visibleTiles = useMemo(
|
|
180
|
-
() =>
|
|
203
|
+
() => arrangedTiles.flatMap((tile) => {
|
|
181
204
|
const chartView = registry.resourceConfigurations[tile.resourceType]?.frontendConfiguration?.chartViews
|
|
182
205
|
?.find((candidate) => candidate.ref === tile.chartViewRef);
|
|
183
206
|
// An unknown chart is an authoring error, and `EmbedChart` throws it with the resource and ref named.
|
|
184
207
|
if (chartView !== undefined && !viewerMayReadChart(chartView.chartDefinition, registry, viewer)) return [];
|
|
185
208
|
return [{ tile, isFigure: chartView?.chartDefinition.chartType === ChartType.KPI }];
|
|
186
209
|
}),
|
|
187
|
-
[
|
|
210
|
+
[arrangedTiles, registry, viewer],
|
|
188
211
|
);
|
|
189
212
|
|
|
190
|
-
if (
|
|
213
|
+
if (layout.readState === ChartDashboardLayoutReadState.LOADING) return null;
|
|
214
|
+
// An administrator keeps the editor even when nothing is left to show: they may have hidden every tile.
|
|
215
|
+
if (visibleTiles.length === 0 && !layout.canEdit) return null;
|
|
191
216
|
const grid = GRID_CLASSES[columns];
|
|
192
217
|
return (
|
|
193
|
-
<div className={cn('@container w-full', className)} data-chart-dashboard>
|
|
194
|
-
<
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
218
|
+
<div className={cn('@container flex w-full flex-col gap-element', className)} data-chart-dashboard>
|
|
219
|
+
{layout.canEdit && <ChartDashboardLayoutControl tiles={tiles} layout={layout} />}
|
|
220
|
+
{visibleTiles.length > 0 && (
|
|
221
|
+
<div className={cn('grid grid-cols-1 gap-group', grid.columns)}>
|
|
222
|
+
{visibleTiles.map(({ tile, isFigure }) => (
|
|
223
|
+
<ChartDashboardTileCell key={`${tile.resourceType}:${tile.chartViewRef}`} tile={tile} isFigure={isFigure} grid={grid} />
|
|
224
|
+
))}
|
|
225
|
+
</div>
|
|
226
|
+
)}
|
|
199
227
|
</div>
|
|
200
228
|
);
|
|
201
229
|
}
|
|
@@ -229,16 +257,115 @@ export function ChartDashboard({ tiles, columns = ChartDashboardColumns.FOUR, cl
|
|
|
229
257
|
* ```
|
|
230
258
|
*/
|
|
231
259
|
export function defineChartDashboardView(
|
|
232
|
-
config: { tiles: readonly ChartDashboardTile[] } & Omit<CompositeViewAuthoringConfig, 'viewComponent'>,
|
|
260
|
+
config: { tiles: readonly ChartDashboardTile[]; columns?: ChartDashboardColumns; layoutRef?: string } & Omit<CompositeViewAuthoringConfig, 'viewComponent'>,
|
|
233
261
|
): CompositeViewAuthoringConfig {
|
|
234
|
-
const { tiles, ...compositeConfig } = config;
|
|
262
|
+
const { tiles, columns, layoutRef, ...compositeConfig } = config;
|
|
235
263
|
function ChartDashboardView(): React.JSX.Element {
|
|
236
264
|
return (
|
|
237
265
|
<CompositeLayout>
|
|
238
|
-
<ChartDashboard tiles={tiles} />
|
|
266
|
+
<ChartDashboard tiles={tiles} columns={columns} layoutRef={layoutRef} />
|
|
239
267
|
</CompositeLayout>
|
|
240
268
|
);
|
|
241
269
|
}
|
|
242
270
|
return defineCompositeView(ChartDashboardView, compositeConfig);
|
|
243
271
|
}
|
|
244
272
|
```
|
|
273
|
+
|
|
274
|
+
## Import Origins
|
|
275
|
+
|
|
276
|
+
- `@wildo-ai/saas-models`
|
|
277
|
+
|
|
278
|
+
## Source Excerpts
|
|
279
|
+
|
|
280
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
/**
|
|
284
|
+
* How many grid columns a dashboard tile spans, where the dashboard is wide enough to have them.
|
|
285
|
+
*
|
|
286
|
+
* Import path: `@wildo-ai/saas-models`.
|
|
287
|
+
*/
|
|
288
|
+
export enum ChartDashboardTileSpan {
|
|
289
|
+
/** One column (the default): a donut, a bar of a few categories. */
|
|
290
|
+
ONE = 'one',
|
|
291
|
+
/** Two columns: a trend over time, a bar of many categories. One column where the dashboard has one. */
|
|
292
|
+
TWO = 'two',
|
|
293
|
+
/** The whole row: a long timeline, a wide table-like chart. */
|
|
294
|
+
FULL = 'full',
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* How many grid rows a dashboard tile spans, where the dashboard has more than one column.
|
|
299
|
+
*
|
|
300
|
+
* Import path: `@wildo-ai/saas-models`.
|
|
301
|
+
*/
|
|
302
|
+
export enum ChartDashboardTileRows {
|
|
303
|
+
/** One row (the default). */
|
|
304
|
+
ONE = 'one',
|
|
305
|
+
/**
|
|
306
|
+
* Two rows: a large chart beside two smaller ones stacked in the next column. Place it right after the first
|
|
307
|
+
* small tile, so the second small tile flows into the row beneath the first: `[small, large (TWO rows), small]`.
|
|
308
|
+
*/
|
|
309
|
+
TWO = 'two',
|
|
310
|
+
}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
## Import Origins
|
|
314
|
+
|
|
315
|
+
- `@wildo-ai/saas-models`
|
|
316
|
+
|
|
317
|
+
## Source Excerpts
|
|
318
|
+
|
|
319
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
320
|
+
|
|
321
|
+
```typescript
|
|
322
|
+
/**
|
|
323
|
+
* One tile of a stored dashboard layout: which declared tile (the resource that declares the chart and the chart view's
|
|
324
|
+
* ref, the pair `ChartDashboard` knows the tile by), its size, and whether the organization hides it. Every field is
|
|
325
|
+
* explicit, so the row reads the same whatever the application later declares as the tile's default size.
|
|
326
|
+
*
|
|
327
|
+
* The size vocabularies declare no `.systemEnum()`: nothing renders this resource through the generic views, and the
|
|
328
|
+
* one surface that shows a size, the layout editor, words its choices itself (`span_<value>`, `rows_<value>` in its
|
|
329
|
+
* component labels). Declaring the vocabulary here too would plan a second set of words for the same values.
|
|
330
|
+
*/
|
|
331
|
+
export const OrganizationDashboardLayoutTileSchema = z.object({
|
|
332
|
+
resourceType: z.string().min(1).max(120).describe('The resource whose chart views declare the tile\'s chart.'),
|
|
333
|
+
chartViewRef: z.string().min(1).max(200).describe('The chart view\'s ref on that resource.'),
|
|
334
|
+
span: z.enum(ChartDashboardTileSpan).describe('How many grid columns the tile spans.'),
|
|
335
|
+
rows: z.enum(ChartDashboardTileRows).describe('How many grid rows the tile spans.'),
|
|
336
|
+
hidden: z.boolean().describe('Whether the organization hides the tile from its dashboard.'),
|
|
337
|
+
});
|
|
338
|
+
export type OrganizationDashboardLayoutTile = z.infer<typeof OrganizationDashboardLayoutTileSchema>;
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* The tiles of a stored layout, in the order the dashboard shows them. A tile appears at most once: two entries for one
|
|
342
|
+
* tile would leave its position and size undecided.
|
|
343
|
+
*/
|
|
344
|
+
export const OrganizationDashboardLayoutTilesSchema = z.array(OrganizationDashboardLayoutTileSchema)
|
|
345
|
+
.max(ORGANIZATION_DASHBOARD_LAYOUT_MAX_TILES)
|
|
346
|
+
.superRefine((tiles, context) => {
|
|
347
|
+
const seen = new Set<string>();
|
|
348
|
+
tiles.forEach((tile, index) => {
|
|
349
|
+
const key = chartDashboardTileKey(tile);
|
|
350
|
+
if (seen.has(key)) context.addIssue({ code: 'custom', path: [index], message: `The tile ${key} appears more than once in the layout.` });
|
|
351
|
+
seen.add(key);
|
|
352
|
+
});
|
|
353
|
+
});
|
|
354
|
+
|
|
355
|
+
/**
|
|
356
|
+
* How one organization arranges one dashboard. `dashboardRef` is the dashboard's `layoutRef`; (`organizationId`,
|
|
357
|
+
* `dashboardRef`) is the row's business key, unique on both stores. Changing it is audited, with the tiles before and after.
|
|
358
|
+
*/
|
|
359
|
+
export const OrganizationDashboardLayoutSchema = z.object({
|
|
360
|
+
_id: z.string().min(1).isPrimaryKey().isSummaryField(),
|
|
361
|
+
organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
|
|
362
|
+
dashboardRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate()
|
|
363
|
+
.describe('The dashboard this layout arranges: the `layoutRef` the application gives it.'),
|
|
364
|
+
tiles: z_clone(OrganizationDashboardLayoutTilesSchema).isAuditEvidence()
|
|
365
|
+
.describe('The dashboard\'s tiles in the order shown, each with its size and whether it is hidden.'),
|
|
366
|
+
createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
|
|
367
|
+
updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
|
|
368
|
+
// One layout per organization and dashboard: the composite business key is a unique constraint on both stores.
|
|
369
|
+
}).businessKeySet(['organizationId', 'dashboardRef']);
|
|
370
|
+
export type OrganizationDashboardLayout = z.infer<typeof OrganizationDashboardLayoutSchema>;
|
|
371
|
+
```
|