@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.
Files changed (60) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  4. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  5. package/dist/esm/framework-knowledge.definitions.js +10 -0
  6. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  7. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -1
  8. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +8 -1
  10. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  11. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  12. package/dist/knowledge/manifest.json +7 -7
  13. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +5 -2
  14. package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +9 -0
  15. package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -1
  16. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +14 -0
  17. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +1 -1
  18. package/dist/knowledge/references/application-maturity.config.md +43 -0
  19. package/dist/knowledge/references/example.infra.environment-config.local.md +2 -2
  20. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +21 -0
  21. package/dist/knowledge/references/platform.config.infrastructure-host.md +1 -0
  22. package/dist/knowledge/references/platform.config.platform-key-management.md +5 -2
  23. package/dist/knowledge/references/requirements.engine-substance.md +38 -0
  24. package/dist/knowledge/references/requirements.functional-requirement.config.md +11 -0
  25. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +11 -0
  26. package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +20 -0
  27. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +72 -0
  28. package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +3 -3
  29. package/dist/knowledge/references/saas.frontend.chart-dashboard.md +38 -35
  30. package/dist/knowledge/references/saas.models.chart-dashboard-tile-sizes.md +40 -0
  31. package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails-environment.md +52 -0
  32. package/dist/knowledge/references/saas.models.organization-dashboard-layout.md +61 -0
  33. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  34. package/dist/knowledge/registries/framework-topics.json +41 -1
  35. package/dist/knowledge/registries/playbooks.json +1 -1
  36. package/dist/knowledge/registries/source-tags.json +1052 -982
  37. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +11 -0
  38. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +43 -0
  39. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +20 -3
  40. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +12 -2
  41. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +16 -4
  42. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +144 -6
  43. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +72 -0
  44. package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +12 -2
  45. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +12 -2
  46. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -1
  47. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -2
  48. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +13 -0
  49. package/dist/knowledge/skills/infra-environment-config/SKILL.md +26 -2
  50. package/dist/knowledge/skills/infra-environment-config/references/framework-agent-content-guardrails-environment-api.md +67 -0
  51. package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +1 -0
  52. package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +5 -2
  53. package/dist/knowledge/skills/provider-backend-package/SKILL.md +17 -3
  54. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +2 -1
  55. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +21 -0
  56. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +1 -1
  57. package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +166 -39
  58. package/dist/knowledge/topic-index.json +197 -58
  59. package/dist/tsconfig.build.tsbuildinfo +1 -1
  60. 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/versions/read`, `…/keys/sign/action`,
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/versions/read`, `…/keys/create/action`, `…/keys/update/action` (disable),
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 the same
146
- classifier the application's agents use (for example
147
- `azure-content-safety`) under `providers.scopes.companion` with
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
@@ -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 that is not a bounded bulk operation, 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
+ | 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
 
@@ -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: {@link ChartDashboardTileSpan.ONE}. */
133
+ /** Grid columns the tile spans (`ChartDashboardTileSpan`, `@wildo-ai/saas-models`). Default: `ONE`. */
130
134
  span?: ChartDashboardTileSpan;
131
- /** Grid rows the tile spans. Default: {@link ChartDashboardTileRows.ONE}. */
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: 280 for a chart; a KPI tile takes
135
- * the height of its figure, and this only sizes its loading placeholder (default 64).
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
- () => tiles.flatMap((tile) => {
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
- [tiles, registry, viewer],
210
+ [arrangedTiles, registry, viewer],
188
211
  );
189
212
 
190
- if (visibleTiles.length === 0) return null;
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
- <div className={cn('grid grid-cols-1 gap-group', grid.columns)}>
195
- {visibleTiles.map(({ tile, isFigure }) => (
196
- <ChartDashboardTileCell key={`${tile.resourceType}:${tile.chartViewRef}`} tile={tile} isFigure={isFigure} grid={grid} />
197
- ))}
198
- </div>
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
+ ```