@wildo-ai/framework-knowledge 1.1.1 → 1.1.2
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/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 +43 -2
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/framework-knowledge.loader.d.ts +19 -0
- package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.loader.js +32 -0
- package/dist/esm/framework-knowledge.loader.js.map +1 -1
- package/dist/esm/framework-knowledge.schemas.d.ts +12 -0
- package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.schemas.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +46 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +4 -4
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +3 -3
- package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -3
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +22 -1
- package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
- package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -1
- package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -13
- package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -4
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -3
- package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +54 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
- package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +76 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +92 -0
- package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +30 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +29 -0
- package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -44
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -53
- package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +31 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +26 -0
- package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -8
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -7
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -3
- package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -3
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
- package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -5
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -4
- package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -0
- package/dist/knowledge/manifest.json +8 -8
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +51 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +43 -0
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +8 -7
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +6 -4
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +5 -4
- package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +0 -4
- package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -6
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +49 -22
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +14 -6
- package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +2 -4
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +46 -1
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +7 -3
- package/dist/knowledge/playbooks/refinement.document-facts/method.md +18 -4
- package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +4 -2
- package/dist/knowledge/playbooks/top_down.brand-identity/method.md +2 -3
- package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +8 -7
- package/dist/knowledge/playbooks/top_down.business-model/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.capability-map/method.md +0 -2
- package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +41 -0
- package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +100 -0
- package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +117 -0
- package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +86 -0
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +61 -0
- package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +41 -0
- package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +21 -4
- package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +14 -57
- package/dist/knowledge/playbooks/top_down.compliance-research/method.md +76 -0
- package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +42 -0
- package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +3 -1
- package/dist/knowledge/playbooks/top_down.market-research/playbook.json +3 -1
- package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -5
- package/dist/knowledge/playbooks/top_down.phase-gate/method.md +8 -4
- package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +9 -7
- package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +2 -2
- package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +8 -7
- package/dist/knowledge/playbooks/top_down.value-proposition/method.md +0 -2
- package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +4 -6
- package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
- package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +8 -7
- package/dist/knowledge/references/companion.technical-doc.service.md +102 -2
- package/dist/knowledge/references/example.config.app-shell.full.md +0 -1
- package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
- package/dist/knowledge/references/platform.config.saas.md +1 -0
- package/dist/knowledge/references/presets.models.surface-policy.md +19 -10
- package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +25 -1
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +45 -0
- package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +34 -0
- package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +45 -0
- package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +65 -0
- package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -0
- package/dist/knowledge/references/saas.models.data-mode-read-list.md +31 -4
- package/dist/knowledge/references/saas.models.engine-capabilities.md +26 -6
- package/dist/knowledge/references/saas.models.file-upload-grant.md +179 -0
- package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +124 -0
- package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +99 -0
- package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +127 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +4 -3
- package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +42 -0
- package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +29 -0
- package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +11 -31
- package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +32 -2
- package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +29 -6
- package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +20 -0
- package/dist/knowledge/references/saas.specifications.resource-spec-config.md +22 -0
- package/dist/knowledge/references/zod.decorators.display-edit-modes.md +6 -0
- package/dist/knowledge/references/zod.decorators.field-spec-params.md +31 -5
- package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +43 -0
- package/dist/knowledge/references/zod.decorators.primitive-ui.md +3 -0
- package/dist/knowledge/references/zod.decorators.shared-structural-params.md +15 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +3 -2
- package/dist/knowledge/registries/framework-topics.json +99 -1
- package/dist/knowledge/registries/playbooks.json +81 -8
- package/dist/knowledge/registries/source-tags.json +757 -588
- package/dist/knowledge/skills/INDEX.md +3 -3
- package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +2 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +5 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +66 -37
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +40 -7
- package/dist/knowledge/skills/config-app-shell/SKILL.md +25 -1
- package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +25 -1
- package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +124 -0
- package/dist/knowledge/skills/config-design-system/SKILL.md +23 -1
- package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +19 -10
- package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +47 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +75 -2
- package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +98 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +54 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +232 -0
- package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +149 -0
- package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +114 -0
- package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +133 -0
- package/dist/knowledge/skills/config-saas/SKILL.md +19 -2
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +111 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +30 -9
- package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +1 -0
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +2 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +4 -3
- package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +20 -0
- package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +20 -0
- package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +20 -0
- package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
- package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +104 -0
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +13 -0
- package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +71 -4
- package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +89 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +22 -1
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +192 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +28 -8
- package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +15 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +6 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +89 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +43 -0
- package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +3 -0
- package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -1
- package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
- package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +20 -0
- package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +31 -5
- package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +22 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +45 -0
- package/dist/knowledge/topic-index.json +504 -156
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +4 -4
- package/dist/esm/.builder.pid +0 -9
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Zone declaration — what one zone in a layout says about itself
|
|
2
|
+
|
|
3
|
+
Read this when authoring or changing a `NavigationLayout`'s `zones` block: what a zone does when its
|
|
4
|
+
last content is dismissed, how much of the zone a destination's content occupies, and the drag bounds
|
|
5
|
+
and responsive behaviour declared alongside them.
|
|
6
|
+
|
|
7
|
+
Read it especially before assuming a default. Three of these fields decide something only when a
|
|
8
|
+
SECOND zone exists, so a single-zone layout gives no feedback about whether they were understood.
|
|
9
|
+
|
|
10
|
+
## Content width belongs to the ZONE, not to your template
|
|
11
|
+
|
|
12
|
+
Every structural zone wraps its content in a boundary that caps at the page-content width
|
|
13
|
+
(`--content-max-width`, 80rem by default) and centres anything wider. A detail pane is almost always
|
|
14
|
+
narrower than that, so in practice the content FILLS the pane — "full width, up to a maximum" — and no
|
|
15
|
+
component has to know how wide its pane is.
|
|
16
|
+
|
|
17
|
+
**Do not cap your own view.** A template that applies its own `max-w-*` and `mx-auto` produces a narrow
|
|
18
|
+
column floating inside a wide pane, and silently disagrees with the cap the zone already applies. If a
|
|
19
|
+
surface genuinely needs to exceed the page-content width — a wide table, a board — declare
|
|
20
|
+
`zoneContentMaxWidth: 'none'` on the operation or view instead.
|
|
21
|
+
|
|
22
|
+
`zoneContentFillsHeight` fills the HEIGHT as well, and is for PRIMARY only. An adjacent zone scrolls, so a
|
|
23
|
+
filling child there would cap at the pane's height and hide the rest; a canvas belongs in primary.
|
|
24
|
+
|
|
25
|
+
## Import Origins
|
|
26
|
+
|
|
27
|
+
- `@wildo-ai/saas-models`
|
|
28
|
+
|
|
29
|
+
## Source Excerpts
|
|
30
|
+
|
|
31
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
*
|
|
35
|
+
* What happens when a zone's last content is dismissed.
|
|
36
|
+
* Only meaningful for secondary and companion zones (primary never empties,
|
|
37
|
+
* overlay auto-dismisses by definition).
|
|
38
|
+
*/
|
|
39
|
+
export enum ZoneEmptyBehavior {
|
|
40
|
+
/**
|
|
41
|
+
* Zone hides, adjacent zones expand to fill the space.
|
|
42
|
+
* Example: closing the last detail → layout returns to list-only.
|
|
43
|
+
* This is the default for all non-primary zones.
|
|
44
|
+
*/
|
|
45
|
+
COLLAPSE = 'collapse',
|
|
46
|
+
/**
|
|
47
|
+
* Zone stays visible with an empty-state placeholder.
|
|
48
|
+
* Example: "Select an item to view details" message. Keeps layout stable.
|
|
49
|
+
* Useful when the user frequently toggles between items.
|
|
50
|
+
*/
|
|
51
|
+
EMPTY_STATE = 'emptyState',
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
*
|
|
59
|
+
* How much of its zone a DESTINATION's content occupies.
|
|
60
|
+
*
|
|
61
|
+
* The primary zone caps and centres its content at `var(--content-max-width, 80rem)` and gives it no
|
|
62
|
+
* definite-height ancestor. That is correct for almost everything a zone hosts — a form, a list, a
|
|
63
|
+
* settings page stretched across a 2560px monitor is unreadable — and wrong for content whose whole
|
|
64
|
+
* value is the space it occupies. Until this enum existed there was no way to tell the two apart, so
|
|
65
|
+
* a canvas had to hand-roll a viewport fraction (`h-[70vh]`), which sizes against the WINDOW rather
|
|
66
|
+
* than the container and therefore ignores whatever chrome sits above it.
|
|
67
|
+
*
|
|
68
|
+
* Declared per DESTINATION rather than per zone: the same primary zone hosts a list that wants the
|
|
69
|
+
* cap, a detail page that caps itself, and a graph that wants neither.
|
|
70
|
+
*
|
|
71
|
+
* Width and height are separable on purpose. A wide data table wants the cap gone and its natural
|
|
72
|
+
* height; collapsing both into one boolean would merge two meanings, and two independent booleans
|
|
73
|
+
* would make "full height, still capped at 80rem" representable — a combination nothing wants and
|
|
74
|
+
* someone would eventually author by accident.
|
|
75
|
+
*/
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Full zone configuration.
|
|
79
|
+
*
|
|
80
|
+
* Each declared zone in the layout owns its complete behavior:
|
|
81
|
+
* which transition fires for each operation, how content appears,
|
|
82
|
+
* and how the zone responds to viewport changes.
|
|
83
|
+
*
|
|
84
|
+
* Note: `minWidth`, `maxWidth`, `defaultVisible`, `onEmpty`,
|
|
85
|
+
* and `responsiveCollapse` are only meaningful for secondary and companion zones.
|
|
86
|
+
* Primary never collapses, never empties, and takes remaining space.
|
|
87
|
+
* Setting these on primary has no effect.
|
|
88
|
+
*/
|
|
89
|
+
export const ZoneConfigSchema = z.object({
|
|
90
|
+
/**
|
|
91
|
+
* How this zone manages multiple items.
|
|
92
|
+
* - `NavigationZoneContentModel.SINGLE` (default): stack-based navigation. One item visible, back pops.
|
|
93
|
+
* - `NavigationZoneContentModel.TABBED`: parallel tabs. Tab bar visible, multiple items accessible.
|
|
94
|
+
* @default NavigationZoneContentModel.SINGLE
|
|
95
|
+
*/
|
|
96
|
+
contentModel: z.enum(NavigationZoneContentModel).default(NavigationZoneContentModel.SINGLE),
|
|
97
|
+
|
|
98
|
+
/** Operation → transition mapping. Defines what happens for each user action in this zone. */
|
|
99
|
+
transitions: ZoneTransitionsSchema,
|
|
100
|
+
|
|
101
|
+
/** Transition → visual appearance. Only split and overlay have appearance choices. */
|
|
102
|
+
appearance: ZoneAppearanceSchema.optional(),
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Minimum pixel width when resizing. Constrains how far this side of the
|
|
106
|
+
* split divider can be dragged. Only meaningful for secondary and companion zones.
|
|
107
|
+
* Works in conjunction with `SplitConfigSchema.resizable`.
|
|
108
|
+
*/
|
|
109
|
+
minWidth: z.number().positive().optional(),
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Maximum pixel width when resizing. Constrains how far this side of the
|
|
113
|
+
* split divider can be dragged. Only meaningful for secondary and companion zones.
|
|
114
|
+
* Works in conjunction with `SplitConfigSchema.resizable`.
|
|
115
|
+
*/
|
|
116
|
+
maxWidth: z.number().positive().optional(),
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Whether this zone is visible on first render (before any transition targets it).
|
|
120
|
+
* - Primary: always visible (this field is ignored).
|
|
121
|
+
* - Secondary: defaults to `true` when `split.autoSplit` is `true`, `false` otherwise.
|
|
122
|
+
* - Companion: defaults to `false` (hidden until a `split` transition targets it or user toggles).
|
|
123
|
+
*/
|
|
124
|
+
defaultVisible: z.boolean().optional(),
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* What happens when this zone's last content is dismissed (stack empty, last tab closed).
|
|
128
|
+
* - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
|
|
129
|
+
* - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
|
|
130
|
+
* Only meaningful for secondary and companion zones. Primary never empties.
|
|
131
|
+
*/
|
|
132
|
+
onEmpty: z.enum(ZoneEmptyBehavior).optional(),
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Responsive collapse rules: what happens when viewport shrinks below the zone's breakpoint.
|
|
136
|
+
* Accepts a plain `ResponsiveCollapseMode` (all breakpoints) or viewport-discriminated object.
|
|
137
|
+
* Only meaningful for secondary and companion zones. Primary never collapses.
|
|
138
|
+
*
|
|
139
|
+
* When viewport grows back past the breakpoint, collapsed content migrates back
|
|
140
|
+
* to its original zone (content is preserved).
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* responsiveCollapse: ResponsiveCollapseMode.PUSH // always push into primary
|
|
144
|
+
* responsiveCollapse: { [ViewportBreakpoint.VERT_TABLET]: ResponsiveCollapseMode.PUSH, [ViewportBreakpoint.MOBILE]: ResponsiveCollapseMode.OVERLAY } // tablet: push, mobile: overlay
|
|
145
|
+
*/
|
|
146
|
+
responsiveCollapse: viewportDiscriminatedSchema(z.enum(ResponsiveCollapseMode)).optional(),
|
|
147
|
+
});
|
|
148
|
+
export type ZoneConfig = z.infer<typeof ZoneConfigSchema>;
|
|
149
|
+
```
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# How a navigation decision is actually made
|
|
2
|
+
|
|
3
|
+
Everything below is the runtime's behaviour, not a convention. Read it before writing a layout, and
|
|
4
|
+
again before concluding that a layout is being ignored.
|
|
5
|
+
|
|
6
|
+
## One event, five tiers, first answer wins
|
|
7
|
+
|
|
8
|
+
Every navigation resolves to exactly one transition verb, chosen from the first tier that answers:
|
|
9
|
+
|
|
10
|
+
1. **The operation's own override** — `navigationOverrides` on a resource operation's frontend config.
|
|
11
|
+
Matched on `fromZone` and `viewport`; first match wins. This is the EXCEPTION channel: one
|
|
12
|
+
operation departing from the layout without the layout knowing.
|
|
13
|
+
2. **The action's presentation** — when an operation declares a presentation (`MODAL` → overlay), that
|
|
14
|
+
is an alias over this same chain rather than a parallel mechanism.
|
|
15
|
+
3. **The viewport block** — `layout[MOBILE]` / `layout[VERT_TABLET]` transition overrides, for sweeping
|
|
16
|
+
responsive behaviour.
|
|
17
|
+
4. **The SOURCE zone's transitions map** — the ordinary case. Note it is the zone you are navigating
|
|
18
|
+
FROM that decides, never the destination.
|
|
19
|
+
5. **The framework fallback.**
|
|
20
|
+
|
|
21
|
+
**A higher tier silently outranks a lower one.** If a layout change appears to do nothing, look UP the
|
|
22
|
+
chain before doubting the layout: an operation-level override answers before any zone map does.
|
|
23
|
+
|
|
24
|
+
## Where each verb puts the content
|
|
25
|
+
|
|
26
|
+
| verb | lands in | keeps the source visible |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `push` / `replace` | the SAME zone | no — one item is visible at a time |
|
|
29
|
+
| `split` | the first adjacent zone (secondary, else companion) | yes — this is the list-detail pattern |
|
|
30
|
+
| `overlay` | the overlay layer | yes, visually; interactivity depends on the overlay's behaviour |
|
|
31
|
+
| `promote` | PRIMARY, clearing secondary and companion | no — it abandons the current context deliberately |
|
|
32
|
+
| `inplace` | nowhere — it transforms an element and changes no zone | |
|
|
33
|
+
|
|
34
|
+
`split` needs an adjacent zone to exist in the layout. If none is declared it escalates to an overlay
|
|
35
|
+
rather than failing, so a layout that "does not split" is usually a layout with one zone.
|
|
36
|
+
|
|
37
|
+
## The URL contract, which decides more than it looks like it does
|
|
38
|
+
|
|
39
|
+
**Structural zones are URL-addressed. The overlay layer is not.**
|
|
40
|
+
|
|
41
|
+
Content in primary, secondary or companion gets a browser URL when its operation is `ADDRESSABLE`, so
|
|
42
|
+
it is linkable, survives a reload, and takes part in browser back and forward. Content in an overlay
|
|
43
|
+
does not: it is a transient layer above the addressed surface.
|
|
44
|
+
|
|
45
|
+
This is the trade behind choosing `overlay` for a detail. A sheet that floats over a canvas costs the
|
|
46
|
+
selection its URL — the reader cannot link a colleague to it, and back does not step through
|
|
47
|
+
selections. That may be the right trade; it should be a decision rather than a discovery.
|
|
48
|
+
|
|
49
|
+
**Which zone owns the URL depends on what is in primary.** Beside a RESOURCE primary the detail owns
|
|
50
|
+
it: a list's detail URL implies the list, so `/tasks/t1` reloads as list + detail. Beside anything
|
|
51
|
+
else — a composite view, a custom view, a chart, an engine page — the PRIMARY keeps the URL and the
|
|
52
|
+
detail rides as a `pane` query parameter: `/composite/board?section=runs&pane=%2Ftasks%2Ft1`. A reload
|
|
53
|
+
restores both; browser back closes the pane; the host's own query params (`?section=`) keep working
|
|
54
|
+
while the pane is open. Nothing to declare: the split transition on the zone is enough, and the
|
|
55
|
+
composition is chosen from what primary holds at the moment of the click.
|
|
56
|
+
|
|
57
|
+
**Query params that are not addresses are view state.** Route ownership compares destinations, not
|
|
58
|
+
URL strings: a view that writes `?section=` or `?dataMode=` onto its own URL keeps its zone entry (no
|
|
59
|
+
rebuild, no remount). Only the framework's context params (`composite_ctx_*`, `chart_ctx_*`,
|
|
60
|
+
`execution_ctx_*`), a chart route's url-param values and `pane` are part of the address.
|
|
61
|
+
|
|
62
|
+
## What a layout declares that the runtime does NOT yet read
|
|
63
|
+
|
|
64
|
+
Stated because the alternative is discovering it by watching nothing happen:
|
|
65
|
+
|
|
66
|
+
- **`ZoneConfig.contentModel` is not read.** `TABBED` in particular is inert — the renderer carries an
|
|
67
|
+
explicit "not yet implemented" note for tabbed zones. A layout selecting it gets `SINGLE` behaviour,
|
|
68
|
+
including the shipped `NAVIGATION_LAYOUT_TABS` preset.
|
|
69
|
+
- **`ZoneConfig.defaultVisible` is not read.**
|
|
70
|
+
- **`SplitConfig.autoSplit` is not read.** A split layout does not pre-open its secondary zone; the
|
|
71
|
+
zone appears when something targets it, and reappears on a deep link because URL restoration places
|
|
72
|
+
the detail there and the list beside it.
|
|
73
|
+
- **`NavigationLayout.maxDepth` is not read.** There is no depth ceiling; do not rely on one.
|
|
74
|
+
|
|
75
|
+
Everything else in `ZoneConfig`, `SplitConfig` and `NavigationLayout` is live.
|
|
76
|
+
|
|
77
|
+
## Three behaviours that read backwards from their field names
|
|
78
|
+
|
|
79
|
+
- **`orientation` names the DIVIDER.** `VERTICAL` is a vertical divider, so the panes sit SIDE BY SIDE;
|
|
80
|
+
`HORIZONTAL` puts the second pane below. This is the opposite of what most panel libraries mean by
|
|
81
|
+
"direction".
|
|
82
|
+
- **`minWidth` is a floor only when the zone cannot collapse.** A collapsible pane treats a minimum as a
|
|
83
|
+
SNAP THRESHOLD and closes past it. Declaring `minWidth` is what asks for a floor.
|
|
84
|
+
- **`ratio` is a percentage and the bounds are pixels**, so they agree at one container width only.
|
|
85
|
+
Below the crossover the opening size is clamped up to the floor rather than honouring the ratio.
|
|
86
|
+
|
|
87
|
+
## Content width is the ZONE's decision
|
|
88
|
+
|
|
89
|
+
Every structural zone caps its content at the page-content width and centres anything wider; a detail
|
|
90
|
+
pane is almost always narrower than that, so content fills it. A view that applies its own `max-w-*`
|
|
91
|
+
and `mx-auto` fights this and produces a narrow column inside a wide pane. Declare
|
|
92
|
+
`zoneContentMaxWidth: 'none'` if content must exceed the cap, and `zoneContentFillsHeight` — primary only — if it must fill the
|
|
93
|
+
height too.
|
|
94
|
+
|
|
95
|
+
## An UNRESOLVED destination decides nothing
|
|
96
|
+
|
|
97
|
+
`onEmpty` and `adjacentZoneOnEmpty` resolve from whatever occupies PRIMARY, and during a page or tab
|
|
98
|
+
change there is a moment when primary's stack has not been reconciled from the URL yet. In that moment
|
|
99
|
+
the destination override is absent — and an absent override is not a destination saying "collapse", it
|
|
100
|
+
is a question nobody has answered.
|
|
101
|
+
|
|
102
|
+
**The engine treats it as a question.** A zone reserves space when empty only once the destination is
|
|
103
|
+
known; until then no structure changes. A zone that HAS content still shows it immediately — having
|
|
104
|
+
content is a fact about the zone, not a decision owned by primary.
|
|
105
|
+
|
|
106
|
+
The consequence for an application: `onEmpty: EMPTY_STATE` on a zone whose destinations override it
|
|
107
|
+
with `COLLAPSE` no longer flashes a reserved pane on every navigation. Measured before the fix on a
|
|
108
|
+
2400px window: the primary content area went 2312 → 1294 → 2312 within ~25ms on each tab click, so the
|
|
109
|
+
page jumped left and back.
|
|
110
|
+
|
|
111
|
+
**You still want the zone-level value to be the one most destinations want.** The gate removes the
|
|
112
|
+
flash, not the disagreement: every destination that overrides the zone still pays a real layout change
|
|
113
|
+
when it resolves. If most of a layout's destinations collapse, declare `COLLAPSE` on the zone and let
|
|
114
|
+
the list-style destinations declare `EMPTY_STATE`.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Everything an application can configure about navigation, and where to declare it
|
|
2
|
+
|
|
3
|
+
Navigation is configured at FOUR levels, and choosing the wrong level is the most common mistake:
|
|
4
|
+
a rule written at the layout level applies to the whole application, and one written on an operation
|
|
5
|
+
applies to that operation only and outranks the layout.
|
|
6
|
+
|
|
7
|
+
| level | file / surface | scope of what you declare |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| **Application layout** | `navigationLayout` in the frontend config | every zone, every operation, the whole app |
|
|
10
|
+
| **Zone** | `layout.zones.<zone>` | one zone's behaviour, for every destination that uses it |
|
|
11
|
+
| **Destination (view)** | a composite view's authoring config | one view's relationship to the zone it occupies |
|
|
12
|
+
| **Destination (operation)** | `navigationOverrides` in `resourceUIBehavior(...).views` | one operation, resolved BEFORE the layout |
|
|
13
|
+
|
|
14
|
+
Read `how-navigation-resolves.md` for the precedence between them. This file is the inventory.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Application layout — `navigationLayout`
|
|
19
|
+
|
|
20
|
+
| field | what it decides | status |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `zones.primary` | the always-present zone. Required. | live |
|
|
23
|
+
| `zones.secondary` | the first adjacent zone. Declaring it is what makes `split` possible at all. | live |
|
|
24
|
+
| `zones.companion` | a second adjacent zone for persistent side content. | live |
|
|
25
|
+
| `appLevel.transitions` | what a SIDEBAR / command-palette / hotkey navigation does. App-level navigation is a layout reset. | live |
|
|
26
|
+
| `appLevel.appearance` | appearance for app-level transitions. | live |
|
|
27
|
+
| `fromOverlay.transitions` | what a navigation STARTED INSIDE an overlay does. | live |
|
|
28
|
+
| `split` | inter-zone geometry — see §3. | live |
|
|
29
|
+
| `backAffordanceOwner` | `SURFACE` (the back control sits in the surface's own header) or `SHELL` (one fixed control in the app shell). One application-wide decision, so the duplication is unrepresentable. | live |
|
|
30
|
+
| `maxDepth` | intended as a depth ceiling. | **NOT READ** |
|
|
31
|
+
| `[MOBILE]` / `[VERT_TABLET]` blocks | sweeping per-viewport transition overrides, merged over zone defaults. | live |
|
|
32
|
+
|
|
33
|
+
## 2. Zone — `layout.zones.<zone>`
|
|
34
|
+
|
|
35
|
+
| field | what it decides | status |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `transitions` | operation → verb, FROM this zone. The ordinary way navigation is configured. | live |
|
|
38
|
+
| `appearance.split` / `appearance.overlay` | which shape a `split` or `overlay` from this zone takes (`PANEL`/`DRAWER`, `DIALOG`/`SHEET`/`DRAWER`). Viewport-discriminable. | live |
|
|
39
|
+
| `onEmpty` | `COLLAPSE` (zone hides, neighbours expand) or `EMPTY_STATE` (zone stays with a placeholder). Adjacent zones only. | live |
|
|
40
|
+
| `minWidth` / `maxWidth` | drag bounds in pixels. Only meaningful with `split.resizable`. **`minWidth` is a floor only because declaring it makes the zone non-collapsible** — see `how-navigation-resolves.md`. | live |
|
|
41
|
+
| `responsiveCollapse` | below the breakpoint, does this zone's content `PUSH` into primary or `OVERLAY` on top. Viewport-discriminable. | live |
|
|
42
|
+
| `contentModel` | `SINGLE` or `TABBED`. | **NOT READ** — `TABBED` is inert |
|
|
43
|
+
| `defaultVisible` | intended as "visible before anything targets it". | **NOT READ** |
|
|
44
|
+
|
|
45
|
+
## 3. Split geometry — `layout.split` (and `split.companion`)
|
|
46
|
+
|
|
47
|
+
| field | what it decides | status |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `ratio` | `[primary, adjacent]` percentages at open. | live |
|
|
50
|
+
| `orientation` | the DIVIDER's orientation: `VERTICAL` → side by side, `HORIZONTAL` → the second pane below. | live |
|
|
51
|
+
| `resizable` | whether the divider can be dragged. **`false` also makes `minWidth`/`maxWidth` inert**, because a static split has no drag to bound. | live |
|
|
52
|
+
| `companion` | the same three fields again, for the companion zone. | live |
|
|
53
|
+
| `autoSplit` | intended as "pre-open the adjacent zone on first load". | **NOT READ** |
|
|
54
|
+
|
|
55
|
+
## 4. Destination — per view
|
|
56
|
+
|
|
57
|
+
On a composite view's authoring config:
|
|
58
|
+
|
|
59
|
+
| field | what it decides |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `adjacentZoneOnEmpty` | overrides the ZONE's `onEmpty` while this view occupies primary. A list wants its detail pane to persist; a canvas wants its width back. One zone, two destinations that disagree. |
|
|
62
|
+
| `zoneContentMaxWidth` | The width cap, in the shared `ResponsiveMaxWidth` vocabulary. Omitted is `'content'` (the page-content cap); `'none'` lets a board or wide table exceed it. |
|
|
63
|
+
| `zoneContentFillsHeight` | Whether the content fills the zone's height too — for a canvas with no intrinsic height. PRIMARY only, because an adjacent zone scrolls. |
|
|
64
|
+
|
|
65
|
+
## 5. Destination — per operation
|
|
66
|
+
|
|
67
|
+
In `resourceUIBehavior(...)`, on a `views` entry:
|
|
68
|
+
|
|
69
|
+
| field | what it decides |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `surface` | `ADDRESSABLE` (a routable page — required for a URL), `EMBEDDED` (renders inside a host, no route of its own), `API_ONLY` (headless). Navigation cannot address an operation that is not `ADDRESSABLE`. |
|
|
72
|
+
| `navigationOverrides[]` | the EXCEPTION. `transition`, `appearance`, `overlayBehavior`, narrowed by `fromZone` and `viewport`. First match wins, resolved ahead of the zone's map. |
|
|
73
|
+
| `adjacentZoneOnEmpty` / `zoneContentMaxWidth` / `zoneContentFillsHeight` | as §4, for a resource operation rather than a view. |
|
|
74
|
+
|
|
75
|
+
### Overlay behaviour — `navigationOverrides[].overlayBehavior`
|
|
76
|
+
|
|
77
|
+
Three independent questions, and a companion panel needs all three answered:
|
|
78
|
+
|
|
79
|
+
| field | default | set it to `false` when |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `modal` | `true` | the reader must keep working the surface behind — a detail beside a live canvas |
|
|
82
|
+
| `closeOnOutsideClick` | `true` | touching that surface must not dismiss. Required alongside `modal: false`: the primitive dismisses on outside pointer-down even when non-modal, so the first drag would close it |
|
|
83
|
+
| `showBackdrop` | `true` | the surface behind must not look DISABLED. A dimmed canvas contradicts an interactive one |
|
|
84
|
+
|
|
85
|
+
## 6. Transition modifiers — `TransitionConfig`
|
|
86
|
+
|
|
87
|
+
A transition is either a bare verb or an object with one modifier:
|
|
88
|
+
|
|
89
|
+
| modifier | valid on | effect |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `persistent` | `split` only | the zone survives the source navigating away, and targets COMPANION specifically rather than the default adjacent resolution. A thread panel that stays open across channels. |
|
|
92
|
+
| `ephemeral` | `overlay` only | auto-closes when the source zone's stack changes. A quick-inspect preview that dismisses when another item is clicked. |
|
|
93
|
+
|
|
94
|
+
`persistent` and `ephemeral` are mutually exclusive; `inplace` and `promote` accept neither.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Width is a CHAIN of three caps — read `framework-content-width-api.md` before changing any of them
|
|
99
|
+
|
|
100
|
+
A surface that will not fill the space it was given is almost always one of three caps, applied in
|
|
101
|
+
sequence and owned by three different parties:
|
|
102
|
+
|
|
103
|
+
| # | Cap | Declared by |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| 1 | the zone's content boundary (page-content width) | `zoneContentMaxWidth` on the destination |
|
|
106
|
+
| 2 | the pane, in an adjacent zone | `ratio` / `minWidth` / `maxWidth`, plus the reader's drag |
|
|
107
|
+
| 3 | the reading measure inside a layout root (~42rem) | `responsiveMaxWidth` on the display or form template |
|
|
108
|
+
|
|
109
|
+
**Fixing the wrong one changes nothing visible**, because a tighter cap is still underneath — which is
|
|
110
|
+
exactly how this was diagnosed three times before it was measured. Read the whole chain in the browser
|
|
111
|
+
before deciding which level owns your case.
|
|
112
|
+
|
|
113
|
+
One behaviour in the chain is a RULE rather than a declaration, because the application has already
|
|
114
|
+
stated its intent: **a record surface's reading measure applies in PRIMARY and not in an adjacent
|
|
115
|
+
zone.** An adjacent pane is already narrow by construction — cap 2 is the application's own statement
|
|
116
|
+
of how wide it should be — so a further cap there cannot improve readability and only leaves a strip
|
|
117
|
+
the reader cannot reclaim by dragging.
|
|
118
|
+
|
|
119
|
+
And in every case: **do not set your own `max-w-*`.** It is a fourth cap, invisible to everything
|
|
120
|
+
above, and it disagrees with the zone the moment a pane is resized.
|
|
121
|
+
|
|
122
|
+
## Choosing a level — the test
|
|
123
|
+
|
|
124
|
+
Ask **who disagrees**.
|
|
125
|
+
|
|
126
|
+
- Every destination behaves this way → the **zone**.
|
|
127
|
+
- Every zone behaves this way → the **layout**.
|
|
128
|
+
- One destination disagrees with the application it lives in → that **destination**.
|
|
129
|
+
- It only differs on small screens → a **viewport** discriminator, at whichever level above.
|
|
130
|
+
|
|
131
|
+
If the answer is "just this one view, and I cannot express it", that is the signal to reach for
|
|
132
|
+
`navigationOverrides` — not for component state. A selection held in `useState` and rendered as a local
|
|
133
|
+
panel looks identical and has no URL, no back, no zone semantics and no responsive collapse.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: config-saas
|
|
3
|
-
description: Edit `wildo.saas.config.ts` for modules, services, engineCapabilities, provider scopes, providerConfigurations, bootstrap,
|
|
3
|
+
description: Edit `wildo.saas.config.ts` for modules, services, engineCapabilities, provider scopes, providerConfigurations, bootstrap, data-service prefixes, and the application's compliance declarations. Use when the user says "add the <module-name> module", "wire a new minion/worker", "enable the <capability> capability", "switch the email provider to <x>", "turn on billing/organizations", "record our legal entity", "declare which jurisdictions we operate in", "set the retention schedule", or any change at the SaaS root that re-shapes app composition or states what is legally true of the application.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Config SaaS
|
|
@@ -47,6 +47,9 @@ this file as ground truth — the only place where the app declares
|
|
|
47
47
|
- Switching runtime provider scope or provider-specific non-secret config
|
|
48
48
|
- Adding a new minion / worker / library
|
|
49
49
|
- Changing data-service prefixes (mongodb / redis / rabbitmq / s3)
|
|
50
|
+
- Declaring the application's legal posture — the operating entity, the jurisdictions it
|
|
51
|
+
operates in, the retention schedule, the AI-use posture, client storage, or per-provider
|
|
52
|
+
compliance choices (see `references/compliance-declarations.md`)
|
|
50
53
|
|
|
51
54
|
## When NOT to Use
|
|
52
55
|
|
|
@@ -73,7 +76,7 @@ entries for shape; rely on TypeScript to validate keys.
|
|
|
73
76
|
|
|
74
77
|
`wildo.saas.config.ts` declares the application topology: services, modules,
|
|
75
78
|
libraries, workers, minions, engine capabilities, provider scopes, and the `specifications` package
|
|
76
|
-
path. The `specifications/` package carries the
|
|
79
|
+
path. The `specifications/` package carries the specification layer that
|
|
77
80
|
explains what that topology means.
|
|
78
81
|
|
|
79
82
|
When you change `wildo.saas.config.ts` or infrastructure config files, update
|
|
@@ -158,6 +161,7 @@ What is **not** in this block (and shouldn't be):
|
|
|
158
161
|
- `references/saas-config-scope.md` — what belongs in root SaaS config
|
|
159
162
|
- `references/framework-wildo-saas-config-api.md` — `WildoSaasConfigSchema` / inferred types
|
|
160
163
|
- `references/framework-provider-capabilities-api.md` — engine slots and provider capability vocabulary, including durable email selection
|
|
164
|
+
- `references/compliance-declarations.md` — the six compliance declarations, and why an ABSENT one is never a negative answer
|
|
161
165
|
|
|
162
166
|
## Verification
|
|
163
167
|
|
|
@@ -167,6 +171,8 @@ What is **not** in this block (and shouldn't be):
|
|
|
167
171
|
- [ ] Every provider used by a runtime scope has a matching declaration in `providers.scopes`
|
|
168
172
|
- [ ] `services` keys referenced by `modules[*].services` actually exist in `services`
|
|
169
173
|
- [ ] Companion sees the updated module list (re-run companion introspection)
|
|
174
|
+
- [ ] No compliance declaration carries an invented value — every one is either the operator's
|
|
175
|
+
own answer or absent (absent is reported as an open gap; invented is published as fact)
|
|
170
176
|
|
|
171
177
|
### Grep invariants
|
|
172
178
|
|
|
@@ -179,6 +185,7 @@ Run from the app root:
|
|
|
179
185
|
| **Module entries ↔ module folders agree** (must return empty) | `comm -3 <(rg -oN "^\s+'\K[a-z-]+(?='\s*:\s*\{)" wildo.saas.config.ts \| sort -u) <(ls -1 shared-lib/src/modules/ \| sort -u)` |
|
|
180
186
|
| Minion / worker paths exist | `rg -oN "path:\s+'\K[^']+" wildo.saas.config.ts \| while read p; do test -d "$p" \|\| echo "MISSING: $p"; done` |
|
|
181
187
|
| Each engine capability declares `enabled:` | `rg -n "EngineCapability\.[A-Z_]+\]:\s*\{" wildo.saas.config.ts \| wc -l` then `rg -c "enabled:" wildo.saas.config.ts` |
|
|
188
|
+
| **No placeholder in a compliance declaration** (must return empty) | `rg -n "TODO\|TBD\|PLACEHOLDER\|example\.com\|Acme" wildo.saas.config.ts` |
|
|
182
189
|
|
|
183
190
|
The third invariant (modules ↔ folders) is the high-signal one — a
|
|
184
191
|
module declared in config without a matching folder breaks `pnpm dev`
|
|
@@ -192,6 +199,10 @@ silently in some pipelines and blocks others on startup.
|
|
|
192
199
|
| "Inline the AI provider key here" | Provider secrets MUST stay in secrets/env. Config only declares **policy** (which providers are allowed); the credentials sit in `wildo-secrets` or env. |
|
|
193
200
|
| "Skip `dataServices.*` prefixes — defaults work" | Defaults collide across apps in shared infra; the prefix declaration is what isolates state per app/environment. |
|
|
194
201
|
| "I'll add a new key not in the schema, the framework will pick it up" | The schema is the contract — unknown keys are dropped or error. Add the field through the framework first if a new dimension is needed. |
|
|
202
|
+
| "Put a placeholder entity name in now and fix it later" | A produced document quotes it as fact. An absent declaration is reported as an open gap a reader can see; an invented one is published. Leave it out. |
|
|
203
|
+
| "The identity needs every field, so I'll wait until I have them all" | Every part is independently declarable — record the half you know. Waiting is how the answer ends up edited into a document that a regeneration then replaces. |
|
|
204
|
+
| "No `operatingJurisdictions` means the app is domestic-only" | Absent means nobody answered. It is not a jurisdiction claim, and no consumer may read it as one. |
|
|
205
|
+
| "The framework warned it knows nothing about a jurisdiction, so drop it" | The application still operates there. Removing it hides a known unknown that belongs in the document's limitations. |
|
|
195
206
|
|
|
196
207
|
## Red Flags
|
|
197
208
|
|
|
@@ -199,6 +210,12 @@ silently in some pipelines and blocks others on startup.
|
|
|
199
210
|
- Minion / worker entry pointing at a non-existent `path` (catch with the **Minion / worker paths exist** check — must return no `MISSING:` lines).
|
|
200
211
|
- Engine capability block lacking `enabled:` (catch with the **Each engine capability declares `enabled:`** check — counts must match).
|
|
201
212
|
- Frontend service with no `frontendType` (implicit defaults are framework-version-dependent; declare it explicitly).
|
|
213
|
+
- A compliance declaration containing a placeholder, an example domain or a plausible-looking
|
|
214
|
+
invented address (catch with the **No placeholder in a compliance declaration** grep — must return empty).
|
|
215
|
+
- `roleAllocations` collapsed to a single role when the product both hosts customer records and
|
|
216
|
+
holds its own account data — that is two roles over two populations, and one is misstated.
|
|
217
|
+
- A `jurisdictionSlug` declared with no `basis`, or a basis that restates the slug ("operates in the EU")
|
|
218
|
+
— the basis exists to say established/selling/holding-data, which imply different obligations.
|
|
202
219
|
|
|
203
220
|
## Related Skills
|
|
204
221
|
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Compliance declarations in `wildo.saas.config.ts`
|
|
2
|
+
|
|
3
|
+
Six optional declarations sit in the root SaaS config alongside the composition keys. They answer a
|
|
4
|
+
different question from the rest of the file — not *"what am I made of"* but *"what is legally true of
|
|
5
|
+
this application"* — and a produced privacy notice or terms document quotes them.
|
|
6
|
+
|
|
7
|
+
Read this before adding or editing any of them.
|
|
8
|
+
|
|
9
|
+
| declaration | answers |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `operatorComplianceIdentity` | who operates the service, in what legal role, on what lawful basis |
|
|
12
|
+
| `operatingJurisdictions` | where the application operates, and why each place reaches it |
|
|
13
|
+
| `dataRetention` | how long each kind of record is kept, and what happens at the end |
|
|
14
|
+
| `aiUsePosture` | what AI features do with the application's data |
|
|
15
|
+
| `clientStorage` | what each frontend surface stores on the user's device |
|
|
16
|
+
| `providerComplianceChoices` | per configured provider, who runs it and where it processes |
|
|
17
|
+
|
|
18
|
+
## The one rule that governs all six: ABSENT is not a value
|
|
19
|
+
|
|
20
|
+
Every one of them is optional, and **absence means nobody has answered — never "no" and never "none"**.
|
|
21
|
+
|
|
22
|
+
That distinction is the whole reason these live in configuration rather than in the document that
|
|
23
|
+
quotes them. A produced document REPLACES its predecessor on every run, so an operator who answers by
|
|
24
|
+
editing the document loses the answer on the next regeneration. Here it survives.
|
|
25
|
+
|
|
26
|
+
So:
|
|
27
|
+
|
|
28
|
+
- **Never** author a placeholder to make a field non-empty. An invented registered address is what a
|
|
29
|
+
data subject would use to serve a legal request on a real company.
|
|
30
|
+
- **Never** read an absent declaration as a negative answer. "No consent is required" and "nobody
|
|
31
|
+
decided what consent is required" are different sentences, and only one of them is safe to publish.
|
|
32
|
+
- A **declared** empty or zero value is usually a real answer and is treated as one — for example
|
|
33
|
+
`serviceConsentRequirement.requiredLevel: NONE` positively states that nothing is gated on consent.
|
|
34
|
+
|
|
35
|
+
## `operatorComplianceIdentity` — fill the part you know
|
|
36
|
+
|
|
37
|
+
Every part is independently declarable. An operator who knows the registered name but has not settled
|
|
38
|
+
lawful bases with counsel records the name; the rest is reported as outstanding and the build is not
|
|
39
|
+
blocked.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
operatorComplianceIdentity: {
|
|
43
|
+
legalEntityName: 'Wonder Software SAS',
|
|
44
|
+
registeredAddress: '1 rue de la Paix, 75002 Paris, France',
|
|
45
|
+
// privacyContact, roleAllocations and lawfulBases may all follow later.
|
|
46
|
+
},
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
What the schema still refuses, and why it is not a contradiction: it refuses an **incoherent** answer,
|
|
50
|
+
never an **absent** one.
|
|
51
|
+
|
|
52
|
+
- an entirely empty object (`{}`) — that is not a partial answer, it is an empty one;
|
|
53
|
+
- `roleAllocations: []` or `lawfulBases: []` — an empty list and an absent key would be two spellings
|
|
54
|
+
of one state, and only absence is honest;
|
|
55
|
+
- a `LEGITIMATE_INTERESTS` basis with no `assessmentNote` — that basis is lawful only where the
|
|
56
|
+
balancing test was actually done, so declaring it without one asserts a conclusion nobody reached;
|
|
57
|
+
- a `serviceConsentRequirement.requiredLevel` above `NONE` with no `gatedProcessing` — a gate nobody
|
|
58
|
+
can describe is a gate nobody can honour.
|
|
59
|
+
|
|
60
|
+
**`roleAllocations` is a LIST because one role is the wrong shape.** A B2B SaaS is typically a
|
|
61
|
+
PROCESSOR for the records its customers put in and a CONTROLLER for the account data of the people who
|
|
62
|
+
administer them — simultaneously, in one product. Collapsing them into one role misstates the
|
|
63
|
+
obligations for one of the two populations.
|
|
64
|
+
|
|
65
|
+
**A consent gate is not a lawful basis.** What a person must agree to in order to proceed, and the
|
|
66
|
+
Art. 6(1) basis the processing rests on, are different questions. Declaring a gate does not make
|
|
67
|
+
consent the basis for anything.
|
|
68
|
+
|
|
69
|
+
## `operatingJurisdictions` — and the warning you must not silence
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
operatingJurisdictions: {
|
|
73
|
+
jurisdictions: [
|
|
74
|
+
{ jurisdictionSlug: 'eu', basis: 'customers established in the EU and their staff use the product' },
|
|
75
|
+
{ jurisdictionSlug: 'us-ca', basis: 'a sales office and customer records held in California' },
|
|
76
|
+
],
|
|
77
|
+
},
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
A slug is an ISO 3166-1 alpha-2 country code, a supranational code such as `eu`, optionally with a
|
|
81
|
+
subdivision suffix (`us-ca`). The `basis` is required: `eu` alone does not say whether the operator is
|
|
82
|
+
established there, sells there, or merely holds data about people there, and those imply different
|
|
83
|
+
obligations.
|
|
84
|
+
|
|
85
|
+
**The framework will tell you where it knows nothing.** A declared jurisdiction that no registered
|
|
86
|
+
assurance source reaches is reported as a KNOWN UNKNOWN, and one reached only by guidance rather than
|
|
87
|
+
by law is reported as such. Those reports belong in the produced document's stated limitations. Do not
|
|
88
|
+
respond to one by removing the jurisdiction — the application still operates there, and a document
|
|
89
|
+
that omits it reads as though every declared place was considered and cleared.
|
|
90
|
+
|
|
91
|
+
Declaring a jurisdiction does not make it covered, and leaving it out does not make it not apply.
|
|
92
|
+
|
|
93
|
+
## The other four, in one line each
|
|
94
|
+
|
|
95
|
+
- **`dataRetention`** — a schedule per record kind. This is the source a retention clause quotes; an
|
|
96
|
+
absent schedule means the notice says retention is not established, not that data is kept forever.
|
|
97
|
+
- **`aiUsePosture`** — what AI features do with application data. Absent means uninventoried; if the
|
|
98
|
+
application declares an AI capability and no posture, a notice must say the question is open.
|
|
99
|
+
- **`clientStorage`** — per frontend surface, what is stored on the device. Here an **empty array is a
|
|
100
|
+
real answer** ("this surface sets nothing of its own") and differs from an absent entry
|
|
101
|
+
("uninventoried"); the two are reported differently.
|
|
102
|
+
- **`providerComplianceChoices`** — per configured provider, who runs it and where it processes. The
|
|
103
|
+
provider declares what is POSSIBLE; this is the operator's CHOICE among those. Without it a produced
|
|
104
|
+
notice would call an audit ledger you host yourself a third-party recipient.
|
|
105
|
+
|
|
106
|
+
## Where these are read
|
|
107
|
+
|
|
108
|
+
Not by the runtime. They are read by the compliance-document lane, which composes a privacy notice or
|
|
109
|
+
service terms from what the application DECLARES rather than from prose about it. That is why an
|
|
110
|
+
invented value is worse than an absent one: an absent declaration is reported as an open gap a reader
|
|
111
|
+
can see, while an invented one is published as fact.
|
|
@@ -66,11 +66,13 @@ export enum EngineCapability {
|
|
|
66
66
|
* extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,
|
|
67
67
|
* which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.
|
|
68
68
|
*
|
|
69
|
-
* ## Not to be confused with
|
|
69
|
+
* ## Not to be confused with PDF GENERATION
|
|
70
70
|
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
* unrelated
|
|
71
|
+
* PDF generation — templates and data become bytes — is the `pdfTemplates` surface, done
|
|
72
|
+
* in-process and with no provider slot of its own. This is the opposite direction: bytes become
|
|
73
|
+
* text. The two are unrelated and nothing routes between them. (There WAS an
|
|
74
|
+
* `EngineCapability.DOCUMENT_GENERATION` that this paragraph used to name; it was withdrawn
|
|
75
|
+
* because no provider capability could ever fill it.)
|
|
74
76
|
*
|
|
75
77
|
* ## Absence is benign, and that is load-bearing
|
|
76
78
|
*
|
|
@@ -97,8 +99,26 @@ export enum EngineCapability {
|
|
|
97
99
|
*/
|
|
98
100
|
AI_CODING_AGENT = 'AI_CODING_AGENT',
|
|
99
101
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
+
/*
|
|
103
|
+
* WITHDRAWN 2026-09-03: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` were members here and are
|
|
104
|
+
* not any more. Neither could ever be filled — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` had no
|
|
105
|
+
* entry pointing at either, so no provider capability token could claim the slot — while both were
|
|
106
|
+
* classified `SELECT_ONE`, which asserts that exactly one provider must be selected. Selecting one
|
|
107
|
+
* of zero candidates is not a resolution mode.
|
|
108
|
+
*
|
|
109
|
+
* Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots
|
|
110
|
+
* costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV
|
|
111
|
+
* and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`
|
|
112
|
+
* surface, with `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) provisioned beside it. Neither
|
|
113
|
+
* has an external provider, and neither is planned to.
|
|
114
|
+
*
|
|
115
|
+
* Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine
|
|
116
|
+
* slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the
|
|
117
|
+
* word landed in whichever they searched first.
|
|
118
|
+
*
|
|
119
|
+
* If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its
|
|
120
|
+
* `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.
|
|
121
|
+
*/
|
|
102
122
|
|
|
103
123
|
FRONTEND_ERROR_MONITORING = 'FRONTEND_ERROR_MONITORING',
|
|
104
124
|
FRONTEND_PRODUCT_ANALYTICS = 'FRONTEND_PRODUCT_ANALYTICS',
|
|
@@ -166,9 +186,10 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
|
|
|
166
186
|
* a read of a PDF's existing text layer. Maps to `EngineCapability.AI_DOCUMENT_EXTRACTION`.
|
|
167
187
|
*
|
|
168
188
|
* A NEW token was genuinely required rather than convenient: `IMAGE_GENERATION` is an OUTPUT
|
|
169
|
-
* capability (text → image), and `
|
|
170
|
-
*
|
|
171
|
-
*
|
|
189
|
+
* capability (text → image), and PDF *generation* — the `pdfTemplates` surface — is this
|
|
190
|
+
* capability's exact opposite. Nothing in the existing vocabulary claimed the document-INPUT
|
|
191
|
+
* slot. (This paragraph used to name `EngineCapability.DOCUMENT_GENERATION`; that member was
|
|
192
|
+
* withdrawn because no provider capability could fill it.)
|
|
172
193
|
*
|
|
173
194
|
* Distinct from `LLM_CHAT` even where a vendor serves both from one API key: the work is
|
|
174
195
|
* different (a page-layout model, billed per page, with no sampling parameters), and fusing
|