@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
package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Loading placeholders — the two things a theme must not decide freely
|
|
2
|
+
|
|
3
|
+
A skeleton is a GHOST OF CONTENT, not a surface of its own. Two consequences a theme gets wrong by
|
|
4
|
+
reaching for a palette entry, both measured on a live application rather than supposed.
|
|
5
|
+
|
|
6
|
+
## 1. The fill is a neutral TINT, never a semantic colour
|
|
7
|
+
|
|
8
|
+
`bg-accent`, `bg-secondary`, `bg-muted` and their siblings carry meaning — and, more importantly, carry
|
|
9
|
+
the APPLICATION's brand. A workbench whose accent resolves to `oklch(0.606 0.25 292)` flashed saturated
|
|
10
|
+
violet slabs on every list, card and detail page while it loaded.
|
|
11
|
+
|
|
12
|
+
They are also OPAQUE, which makes them correct on exactly the one surface they were picked against. The
|
|
13
|
+
same skeleton renders on the page, inside a raised card, inside a muted panel and inside an overlay.
|
|
14
|
+
|
|
15
|
+
Use `SKELETON_NEUTRAL_TINT` from `@wildo-ai/presets-components-models` — a low-alpha tint of the
|
|
16
|
+
foreground. It composites correctly on every surface and inverts for free in dark mode, because
|
|
17
|
+
`--foreground` already does.
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
const skeleton: UIBehaviorRecipe = recipe({
|
|
21
|
+
base: `${SKELETON_NEUTRAL_TINT} animate-pulse ${MY.radius} motion-reduce:animate-none`,
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
A theme still owns radius, border and animation — its idiom. A theme that needs a different strength
|
|
26
|
+
changes the ALPHA (`bg-foreground/5`) rather than reaching for a palette token.
|
|
27
|
+
|
|
28
|
+
## 2. A COLLECTION repeats its silhouette
|
|
29
|
+
|
|
30
|
+
A template describes ONE thing. Drawing one of them on a list tells the reader "one item is coming"
|
|
31
|
+
while twenty are, and it is the most common complaint about skeletons: *I cannot tell what these are.*
|
|
32
|
+
|
|
33
|
+
`Skeleton` takes a `count`. A collection knows its page size, so it says so — and the framework's own
|
|
34
|
+
list layout already does this for every resource. The count is clamped, so a page size of 100 does not
|
|
35
|
+
paint a wall of grey.
|
|
36
|
+
|
|
37
|
+
**Match the silhouette to what the collection actually draws, which is two questions rather than one.**
|
|
38
|
+
A table draws rows; so does a CARDS collection whose `cardLayout.style` is `LIST` — the classic stacked
|
|
39
|
+
list of one-line entries. Only a card GRID draws the tall card shape. Keying on the display mode alone
|
|
40
|
+
gives a page of 128px blocks above a list of one-line rows.
|
|
41
|
+
|
|
42
|
+
## What you do not have to do
|
|
43
|
+
|
|
44
|
+
Nothing, for an ordinary application. Both behaviours are the framework default: the shipped themes
|
|
45
|
+
carry the neutral tint, and `ResourceLayout_List` passes the template and count for every resource
|
|
46
|
+
list. This page matters when you AUTHOR a theme, or when a custom collection surface draws its own
|
|
47
|
+
loading state.
|
|
@@ -63,22 +63,83 @@ Open `frontend/src/config/navigation.config.ts`.
|
|
|
63
63
|
|
|
64
64
|
### Step 2: Read constraints
|
|
65
65
|
|
|
66
|
+
`references/how-navigation-resolves.md`
|
|
67
|
+
`references/navigation-configuration-map.md`
|
|
68
|
+
`references/framework-navigation-vocabulary-api.md`
|
|
66
69
|
`references/navigation-zones.md`
|
|
67
70
|
`references/framework-navigation-layout-api.md`
|
|
71
|
+
`references/framework-navigation-zone-declaration-api.md`
|
|
68
72
|
|
|
69
73
|
Understand the **resolution order** (per-resource override → per-relationship
|
|
70
74
|
override → viewport override → zone transitions → framework fallback)
|
|
71
75
|
before changing any block — edits to a higher tier silently override
|
|
72
76
|
lower-tier rules.
|
|
73
77
|
|
|
74
|
-
### Step
|
|
78
|
+
### Step 2b: Read a second zone's declaration before adding one
|
|
79
|
+
|
|
80
|
+
Most of `ZoneConfig` decides nothing until a SECOND zone exists. A single-zone
|
|
81
|
+
layout accepts `onEmpty`, `minWidth`, `maxWidth` and `responsiveCollapse` and
|
|
82
|
+
gives no feedback about whether any of them was understood, because none of
|
|
83
|
+
them can apply. Adding a secondary zone makes all four live at once.
|
|
84
|
+
|
|
85
|
+
Three of them behave in ways the field name does not imply:
|
|
86
|
+
|
|
87
|
+
- **`orientation` names the DIVIDER, not the stacking axis.** `VERTICAL` is a
|
|
88
|
+
vertical divider, which puts the panes SIDE BY SIDE; `HORIZONTAL` puts the
|
|
89
|
+
second pane below. The schema example says so and it is the opposite of what
|
|
90
|
+
most panel libraries mean by "direction".
|
|
91
|
+
- **`minWidth` is a floor only when the zone cannot collapse.** A collapsible
|
|
92
|
+
panel treats a minimum as a SNAP THRESHOLD: dragging past it closes the pane
|
|
93
|
+
rather than stopping. Declaring `minWidth` is what asks for a floor.
|
|
94
|
+
- **`ratio` is a percentage and the bounds are pixels**, so the two agree at one
|
|
95
|
+
container width only. Below the crossover the ratio is clamped up to the
|
|
96
|
+
floor — the pane opens at its minimum rather than at the share you wrote.
|
|
97
|
+
|
|
98
|
+
### Step 2c: Choose the LEVEL before choosing the value
|
|
99
|
+
|
|
100
|
+
Navigation is configured at four levels — application layout, zone, destination view, destination
|
|
101
|
+
operation — and the same behaviour is expressible at more than one of them. Picking the wrong level is
|
|
102
|
+
the most common mistake here, because it works for the surface in front of you and quietly changes
|
|
103
|
+
every other one.
|
|
104
|
+
|
|
105
|
+
`references/navigation-configuration-map.md` is the inventory. The test is **who disagrees**:
|
|
106
|
+
|
|
107
|
+
- every destination behaves this way → the **zone**
|
|
108
|
+
- every zone behaves this way → the **layout**
|
|
109
|
+
- one destination disagrees with the application it lives in → that **destination**
|
|
110
|
+
- it only differs on small screens → a **viewport** discriminator at whichever level above
|
|
111
|
+
|
|
112
|
+
### Step 3: Decide whether this is a LAYOUT rule or an EXCEPTION
|
|
113
|
+
|
|
114
|
+
A `NavigationLayout` states what happens for a whole application: from this
|
|
115
|
+
zone, this operation resolves to this transition. Some destinations genuinely
|
|
116
|
+
disagree with the application they live in — a canvas whose detail must float
|
|
117
|
+
over it rather than take 40% of it, a list that wants its detail pane to
|
|
118
|
+
persist while a reviewer steps through rows.
|
|
119
|
+
|
|
120
|
+
Express that as a per-operation override, never as component state:
|
|
121
|
+
|
|
122
|
+
`references/framework-navigation-operation-override-api.md`
|
|
123
|
+
|
|
124
|
+
The declaration lives on the operation and is resolved BEFORE the zone's own
|
|
125
|
+
transition map, so one operation departs from the layout without the layout
|
|
126
|
+
knowing. `fromZone` narrows it further when the same operation should behave
|
|
127
|
+
differently depending on where it was reached from.
|
|
128
|
+
|
|
129
|
+
The alternative an author reaches for — holding the selection in `useState` and
|
|
130
|
+
rendering a panel beside the content — produces something that looks identical
|
|
131
|
+
and has none of the framework's behaviour: no URL, no back navigation, no zone
|
|
132
|
+
semantics, no responsive collapse. If a detail surface cannot be linked to, that
|
|
133
|
+
is the tell.
|
|
134
|
+
|
|
135
|
+
### Step 4: Edit the layout
|
|
75
136
|
|
|
76
137
|
Mirror the canonical zone-first shape: every zone declares `contentModel`,
|
|
77
138
|
`transitions`, and `appearance`. The `appLevel` and `fromOverlay` blocks
|
|
78
139
|
are first-class siblings to `zones`, not nested inside them. Viewport
|
|
79
140
|
overrides are top-level keyed by `ViewportBreakpoint.*`.
|
|
80
141
|
|
|
81
|
-
### Step
|
|
142
|
+
### Step 5: Align consumers
|
|
82
143
|
|
|
83
144
|
If new zones are introduced, update `views-app-level` registrations so
|
|
84
145
|
launcher items can target them. Per-resource overrides in
|
|
@@ -198,8 +259,20 @@ What is **not** in this block (and shouldn't be):
|
|
|
198
259
|
|
|
199
260
|
## References
|
|
200
261
|
|
|
262
|
+
- `references/navigation-configuration-map.md` — **the inventory**: every configurable aspect, which of
|
|
263
|
+
- `references/framework-content-width-api.md` — the three width caps between a zone and a line of text, who owns each, and the reading-measure tier a display template declares.
|
|
264
|
+
the four levels it is declared at, what it decides, and which fields the runtime does not read
|
|
265
|
+
- `references/how-navigation-resolves.md` — **read first**: the five-tier resolution order, where each
|
|
266
|
+
transition puts content, the URL contract, what a layout may declare that the runtime does not read,
|
|
267
|
+
and the fields whose names read backwards
|
|
268
|
+
- `references/framework-navigation-vocabulary-api.md` — the transition verbs and the surface
|
|
269
|
+
vocabularies the layout schema is written in
|
|
201
270
|
- `references/navigation-zones.md` — zone / transition concepts for authors
|
|
202
271
|
- `references/framework-navigation-layout-api.md` — engine `NavigationLayoutSchema` / `NavigationLayout`
|
|
272
|
+
- `references/framework-navigation-zone-declaration-api.md` — what ONE zone declares: `onEmpty`,
|
|
273
|
+
`zoneContentMaxWidth` / `zoneContentFillsHeight`, drag bounds, responsive collapse
|
|
274
|
+
- `references/framework-navigation-operation-override-api.md` — the per-operation EXCEPTION: a
|
|
275
|
+
different transition, appearance or overlay behaviour for one operation
|
|
203
276
|
|
|
204
277
|
## Verification
|
|
205
278
|
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Content width — who decides how wide a surface may be
|
|
2
|
+
|
|
3
|
+
Read this when a surface looks narrower than the space it was given: a detail pane with a column of
|
|
4
|
+
content and dead space beside it, a board or a table that will not use a wide monitor, a document
|
|
5
|
+
squeezed while its container is not.
|
|
6
|
+
|
|
7
|
+
There are **three** caps between a zone and a line of text, they apply in sequence, and each is owned
|
|
8
|
+
by a different party. Almost every "it will not fill the pane" report is one of the three, and fixing
|
|
9
|
+
the wrong one changes nothing visible because a tighter one is still underneath.
|
|
10
|
+
|
|
11
|
+
| # | Cap | Owned by | How to change it |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| 1 | The zone's content boundary — the page-content width (`content`, ~80rem) | the destination in the zone | `zoneContentMaxWidth` on the view or operation |
|
|
14
|
+
| 2 | The pane itself, in an adjacent zone | the navigation layout | `ratio`, `minWidth`, `maxWidth` on the zone, plus the reader's drag |
|
|
15
|
+
| 3 | The reading measure inside a layout root (~42rem) | the display or form TEMPLATE | `responsiveMaxWidth` below |
|
|
16
|
+
|
|
17
|
+
Cap 3 is the one that surprises people, because it is the tightest and the least visible: it sits
|
|
18
|
+
inside the template, so widening the pane does not move it.
|
|
19
|
+
|
|
20
|
+
## Finding which cap is binding — do this FIRST
|
|
21
|
+
|
|
22
|
+
Every element that decides a width announces its tier, so the whole chain is one call in the console:
|
|
23
|
+
|
|
24
|
+
Select the element that looks too narrow in the inspector (so it is `$0`), then:
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
// every cap ABOVE the selected element, outermost first — the binding one is the narrowest row
|
|
28
|
+
[...document.querySelectorAll('[data-inline-size-tier]')]
|
|
29
|
+
.filter((el) => el.contains($0))
|
|
30
|
+
.map((el) => [el.dataset.inlineSizeTier, Math.round(el.getBoundingClientRect().width), el.dataset.slot ?? el.tagName]);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Filter by ancestry rather than listing the whole page: a card, a node and a dialog each declare a tier
|
|
34
|
+
too, so a page-wide listing is dominated by leaves that cap nothing above your content.
|
|
35
|
+
|
|
36
|
+
Read it before changing anything. **Fixing a cap that is not the binding one changes nothing visible**,
|
|
37
|
+
because a tighter cap is still underneath — which is how the wrong level got fixed twice in a row on
|
|
38
|
+
the workbench artifact before anyone measured. The binding cap is the narrowest row, not the outermost.
|
|
39
|
+
|
|
40
|
+
## Declaring the reading measure
|
|
41
|
+
|
|
42
|
+
## Import Origins
|
|
43
|
+
|
|
44
|
+
- `@wildo-ai/saas-frontend-lib`
|
|
45
|
+
|
|
46
|
+
## Source Excerpts
|
|
47
|
+
|
|
48
|
+
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
export interface DisplayLayoutProps {
|
|
52
|
+
/** Additional CSS classes for the root container. */
|
|
53
|
+
className?: string;
|
|
54
|
+
/**
|
|
55
|
+
* How wide the layout root lets its content grow, named in the framework's own vocabulary.
|
|
56
|
+
*
|
|
57
|
+
* Defaults to `'measure'` — the reading-measure cap (~42rem, themeable via `--measure-max-width`)
|
|
58
|
+
* that keeps a single-column stack of label/value pairs readable instead of stretched edge to edge.
|
|
59
|
+
* That default is right for what this layout was built for and is unchanged.
|
|
60
|
+
*
|
|
61
|
+
* It is WRONG for a composed document. A template that renders tabs, quote blocks, tables or regions
|
|
62
|
+
* is not a field stack: those set their own measure internally, and a 42rem cap around them squeezes
|
|
63
|
+
* the whole composition into a column with dead space beside it. Such a template declares `'none'`.
|
|
64
|
+
*
|
|
65
|
+
* `'none'` is not "uncapped" in practice — the zone content boundary above has already capped the
|
|
66
|
+
* area at the page-content width (`'content'`, ~80rem) and an adjacent pane is narrower still. This
|
|
67
|
+
* prop decides only whether a SECOND, tighter cap applies inside that, and the answer depends on what
|
|
68
|
+
* the template renders, which is why the template is the one asked.
|
|
69
|
+
*/
|
|
70
|
+
responsiveMaxWidth?: ResponsiveMaxWidth;
|
|
71
|
+
children?: ReactNode;
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`FormLayout` carries the identical prop, with the same default.
|
|
76
|
+
|
|
77
|
+
## Choosing a tier
|
|
78
|
+
|
|
79
|
+
- **Leave the default** for a single column of label/value pairs, settings rows or form inputs. That
|
|
80
|
+
is what the measure exists for: such a stack really is unreadable stretched across a wide zone, and
|
|
81
|
+
the cap is not a bug to route around.
|
|
82
|
+
- **Declare `'none'`** for a composed DOCUMENT — tabs, regions, tables, quote blocks, prose sections.
|
|
83
|
+
Those set their own measure internally, so an outer 42rem cap improves no line of text and only
|
|
84
|
+
leaves a strip the reader cannot reclaim by dragging.
|
|
85
|
+
- `'none'` is never actually uncapped: caps 1 and 2 are still above it. It removes a second, tighter
|
|
86
|
+
cap inside a boundary the framework has already applied.
|
|
87
|
+
|
|
88
|
+
## If the decision is the same for a family of templates
|
|
89
|
+
|
|
90
|
+
Wrap it once. Sixteen templates each spelling `responsiveMaxWidth="none"` is one decision recorded
|
|
91
|
+
sixteen times, and the seventeenth template will be written without it. A small local layout component
|
|
92
|
+
that the family's templates import instead means a new member gets the right measure by construction.
|
|
93
|
+
|
|
94
|
+
## What NOT to do
|
|
95
|
+
|
|
96
|
+
Do not set your own `max-w-*` on a template root. It is a fourth cap, invisible to everything above,
|
|
97
|
+
and it disagrees with the zone the moment a pane is resized. Every width in the chain above has a
|
|
98
|
+
declaration; use the one at the level that owns the question.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Per-operation navigation override — the exception to the layout
|
|
2
|
+
|
|
3
|
+
Read this when ONE operation must not follow the layout's global behaviour: a detail that belongs in a
|
|
4
|
+
sheet while every other detail splits, an overlay that must not block the surface behind it, an
|
|
5
|
+
appearance that differs at one breakpoint.
|
|
6
|
+
|
|
7
|
+
This is the supported way to express an exception. The alternative an author reaches for — holding the
|
|
8
|
+
selection in component state and rendering a panel locally — produces something that looks the same and
|
|
9
|
+
has none of the framework's behaviour: no URL, no back navigation, no zone semantics, no responsive
|
|
10
|
+
collapse.
|
|
11
|
+
|
|
12
|
+
## Import Origins
|
|
13
|
+
|
|
14
|
+
- `@wildo-ai/saas-frontend-lib`
|
|
15
|
+
|
|
16
|
+
## Source Excerpts
|
|
17
|
+
|
|
18
|
+
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
19
|
+
|
|
20
|
+
```typescript
|
|
21
|
+
*
|
|
22
|
+
* Per-operation navigation chrome: transition, overlay/split appearance, source zone.
|
|
23
|
+
*
|
|
24
|
+
* **How to use:** attach fragments of this shape under
|
|
25
|
+
* `ResourceOperationFrontendConfig.navigationOverrides` in `resourceUIBehavior()`.
|
|
26
|
+
* Each override applies when navigating **from** the configured zone/viewport into
|
|
27
|
+
* this operation. Prefer mirroring a sibling resource that already matches the
|
|
28
|
+
* product’s overlay vs split behavior.
|
|
29
|
+
*/
|
|
30
|
+
export const NavigationOperationOverrideSchema = z.object({
|
|
31
|
+
transition: TransitionConfigSchema,
|
|
32
|
+
appearance: viewportDiscriminatedSchema(z.union([
|
|
33
|
+
z.enum(OverlayAppearance),
|
|
34
|
+
z.enum(SplitAppearance),
|
|
35
|
+
])).optional(),
|
|
36
|
+
fromZone: z.union([z.enum(NavigationZoneName), z.literal('appLevel')]).optional(),
|
|
37
|
+
viewport: z.enum(ViewportBreakpoint).optional(),
|
|
38
|
+
/**
|
|
39
|
+
* Behaviour of the OVERLAY this override resolves to — whether the page behind stays interactive,
|
|
40
|
+
* whether touching it dismisses, whether it is dimmed. Ignored for non-overlay transitions.
|
|
41
|
+
*
|
|
42
|
+
* These three were already declared on `OverlayContainerConfig` with documented defaults and read by
|
|
43
|
+
* nothing; they are honoured now, and this is the channel that lets a NAVIGATION-driven overlay set
|
|
44
|
+
* them. Declared per operation because it describes the CONTENT: an application legitimately has a
|
|
45
|
+
* create dialog that blocks everything and a detail sheet beside a live canvas that blocks nothing.
|
|
46
|
+
*/
|
|
47
|
+
overlayBehavior: z.object({
|
|
48
|
+
modal: z.boolean().optional(),
|
|
49
|
+
closeOnOutsideClick: z.boolean().optional(),
|
|
50
|
+
showBackdrop: z.boolean().optional(),
|
|
51
|
+
}).optional(),
|
|
52
|
+
});
|
|
53
|
+
export type NavigationOperationOverride = z.infer<typeof NavigationOperationOverrideSchema>;
|
|
54
|
+
```
|
package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# The vocabularies a navigation layout is written in
|
|
2
|
+
|
|
3
|
+
Read this first. A `NavigationLayout` is almost entirely these closed vocabularies, and every field in
|
|
4
|
+
the layout schema is one of them — so the schema is unreadable without them.
|
|
5
|
+
|
|
6
|
+
Two questions, two vocabularies:
|
|
7
|
+
|
|
8
|
+
- **What HAPPENS** — the transition verbs. Six of them, and each one answers "where does the content go
|
|
9
|
+
relative to where I am".
|
|
10
|
+
- **WHERE and HOW it renders** — the zones, the content model, the responsive collapse modes, and the
|
|
11
|
+
appearance a split or an overlay takes.
|
|
12
|
+
|
|
13
|
+
## Import Origins
|
|
14
|
+
|
|
15
|
+
- `@wildo-ai/saas-models`
|
|
16
|
+
|
|
17
|
+
## Source Excerpts
|
|
18
|
+
|
|
19
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
*/
|
|
23
|
+
export enum NavigationTransition {
|
|
24
|
+
/**
|
|
25
|
+
* Content added to the zone's stack (single) or as a new tab (tabbed).
|
|
26
|
+
* Back navigation pops the stack or switches to the previous tab.
|
|
27
|
+
* URL adds a new path segment.
|
|
28
|
+
*/
|
|
29
|
+
PUSH = 'push',
|
|
30
|
+
/**
|
|
31
|
+
* Content replaces the current content in the zone. No stack entry — the previous
|
|
32
|
+
* content is gone from the zone's state (but remains in browser history).
|
|
33
|
+
* URL replaces the current segment.
|
|
34
|
+
*/
|
|
35
|
+
REPLACE = 'replace',
|
|
36
|
+
/**
|
|
37
|
+
* Content opens in an adjacent zone (secondary or companion).
|
|
38
|
+
* Creates a side-by-side layout. The source zone's content remains visible.
|
|
39
|
+
* Back navigation un-splits (closes the adjacent zone).
|
|
40
|
+
* URL adds a split segment.
|
|
41
|
+
*/
|
|
42
|
+
SPLIT = 'split',
|
|
43
|
+
/**
|
|
44
|
+
* Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
|
|
45
|
+
* The underlying layout remains visible but non-interactive.
|
|
46
|
+
* Back navigation or Escape dismisses the overlay.
|
|
47
|
+
* URL adds an overlay param/hash.
|
|
48
|
+
*/
|
|
49
|
+
OVERLAY = 'overlay',
|
|
50
|
+
/**
|
|
51
|
+
* Element-level transformation within the current view. A specific item in a
|
|
52
|
+
* list/section transforms from one mode to another (read → edit); a CREATE
|
|
53
|
+
* materializes a new element beside the existing ones. The parent view stays,
|
|
54
|
+
* the zone stack is unchanged, and surrounding items remain visible.
|
|
55
|
+
*
|
|
56
|
+
* Fundamentally different from `replace` (which swaps the entire zone content).
|
|
57
|
+
* `inplace` operates at the element level, not the zone level.
|
|
58
|
+
*
|
|
59
|
+
* No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `inplace`.
|
|
60
|
+
* No appearance to configure — the element transforms within its existing slot.
|
|
61
|
+
*
|
|
62
|
+
* **It is the one transition that does not place content in a zone**, which is
|
|
63
|
+
* why the controller hands it to the element-level host
|
|
64
|
+
* (`InPlaceOperationContext`) instead of resolving a target zone for it. That
|
|
65
|
+
* host is provided by the COLLECTION the element belongs to, so a transition
|
|
66
|
+
* resolving to `inplace` on a surface with no collection above it — a detail
|
|
67
|
+
* page, a breadcrumb, a picker — degrades to an OVERLAY.
|
|
68
|
+
*
|
|
69
|
+
* **It is TRANSIENT: no URL, and a reload returns the view to rest.** Earlier
|
|
70
|
+
* revisions of this comment promised a query param (`?editing=<childId>` /
|
|
71
|
+
* `?creating=<resourceType>`) and none was ever written. It is not written now
|
|
72
|
+
* either, and that is a decision rather than an omission: an inline row-edit is
|
|
73
|
+
* a momentary state of a listing, not a place — no comparable admin framework
|
|
74
|
+
* deep-links one, and anything that should survive a reload or a back button
|
|
75
|
+
* wants `push`. `ResourceOperationActionPresentation.INLINE`, the per-operation
|
|
76
|
+
* tier that selects the same host, is transient for the same reason.
|
|
77
|
+
*
|
|
78
|
+
* @example
|
|
79
|
+
* // Click "edit" on a child in parent's inline section → item transforms to edit form
|
|
80
|
+
* transitions: { [CoreResourceOperation.UPDATE]: NavigationTransition.INPLACE }
|
|
81
|
+
*
|
|
82
|
+
* // Click "add" in a relationship section → create form appears inline in the list
|
|
83
|
+
* transitions: { [CoreResourceOperation.CREATE]: NavigationTransition.INPLACE }
|
|
84
|
+
*/
|
|
85
|
+
INPLACE = 'inplace',
|
|
86
|
+
/**
|
|
87
|
+
* Escape the current context and open content at primary scope.
|
|
88
|
+
* Abandons the current context: overlays close, companion/secondary dismiss.
|
|
89
|
+
* The promoted content becomes the primary zone's top content.
|
|
90
|
+
*
|
|
91
|
+
* Use case: a link within an overlay should open as a full primary view,
|
|
92
|
+
* or a nested detail in a companion zone should "pop out" to primary.
|
|
93
|
+
*
|
|
94
|
+
* Fundamentally different from `push` (which stays in the current zone) and
|
|
95
|
+
* from `replace` (which replaces content within the same zone). `promote`
|
|
96
|
+
* crosses zones and always targets primary.
|
|
97
|
+
*
|
|
98
|
+
* No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `promote`.
|
|
99
|
+
* No appearance to configure — content fills primary (same as push/replace).
|
|
100
|
+
*
|
|
101
|
+
* URL serialization: full URL change (promoted resource becomes the primary route).
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* // From an overlay, a link should open as primary (close overlay, show in primary)
|
|
105
|
+
* transitions: { [CoreResourceOperation.READ]: NavigationTransition.PROMOTE }
|
|
106
|
+
*/
|
|
107
|
+
PROMOTE = 'promote',
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Import Origins
|
|
112
|
+
|
|
113
|
+
- `@wildo-ai/saas-models`
|
|
114
|
+
|
|
115
|
+
## Source Excerpts
|
|
116
|
+
|
|
117
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
*/
|
|
121
|
+
export enum NavigationZoneName {
|
|
122
|
+
/** Main content area. Lists, root-level reads, primary workspace. Always exists. */
|
|
123
|
+
PRIMARY = 'primary',
|
|
124
|
+
/**
|
|
125
|
+
* First adjacent zone. Detail content in list-detail patterns.
|
|
126
|
+
* Only exists if declared in config. Appears when a `split` transition targets it.
|
|
127
|
+
* Typical use: showing item details alongside a list.
|
|
128
|
+
*/
|
|
129
|
+
SECONDARY = 'secondary',
|
|
130
|
+
/**
|
|
131
|
+
* Persistent supplementary content. Reference panels, docs, notes, threads.
|
|
132
|
+
* Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
|
|
133
|
+
* Activated by `split` with `persistent: true` or explicit user toggle.
|
|
134
|
+
* Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
|
|
135
|
+
*/
|
|
136
|
+
COMPANION = 'companion',
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* How a zone manages multiple items. Orthogonal to transitions.
|
|
141
|
+
*
|
|
142
|
+
* The transition says "content arrives" — the content model says
|
|
143
|
+
* "how does the zone accommodate it." Any zone can use any content model,
|
|
144
|
+
* regardless of which transitions it supports.
|
|
145
|
+
*/
|
|
146
|
+
export enum NavigationZoneContentModel {
|
|
147
|
+
/**
|
|
148
|
+
* Navigation stack: new content pushes on top, previous preserved underneath.
|
|
149
|
+
* Only one item visible at a time. Back navigation pops the stack.
|
|
150
|
+
* `replace` replaces the top without adding to the stack.
|
|
151
|
+
* This is the default for all zones.
|
|
152
|
+
*/
|
|
153
|
+
SINGLE = 'single',
|
|
154
|
+
/**
|
|
155
|
+
* Parallel tabs: `push` creates a new tab (or activates existing for the same resource).
|
|
156
|
+
* Tab bar is visible, showing all open tabs. No depth stack within tabs.
|
|
157
|
+
* `replace` replaces the active tab's content. Close is an explicit action (not back).
|
|
158
|
+
* When no tabs remain, `onEmpty` behavior applies.
|
|
159
|
+
*/
|
|
160
|
+
TABBED = 'tabbed',
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Responsive collapse behavior when viewport shrinks below a zone's breakpoint.
|
|
165
|
+
*
|
|
166
|
+
* Only applies to secondary and companion zones. Primary never collapses.
|
|
167
|
+
* When viewport grows back past the breakpoint, collapsed content migrates
|
|
168
|
+
* back to its original zone (content is preserved).
|
|
169
|
+
*/
|
|
170
|
+
export enum ResponsiveCollapseMode {
|
|
171
|
+
/**
|
|
172
|
+
* Zone hides. Its content joins primary's navigation stack.
|
|
173
|
+
* The user sees the content in-context within primary.
|
|
174
|
+
* Back navigation pops back to primary's previous content.
|
|
175
|
+
*/
|
|
176
|
+
PUSH = 'push',
|
|
177
|
+
/**
|
|
178
|
+
* Zone hides. Its content opens as an overlay on top of primary.
|
|
179
|
+
* The user sees the content as a floating sheet/dialog.
|
|
180
|
+
* Dismiss returns to the underlying primary content.
|
|
181
|
+
*/
|
|
182
|
+
OVERLAY = 'overlay',
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
*
|
|
190
|
+
* Visual presentation for overlay transitions.
|
|
191
|
+
* Determines how floating content renders above the layout.
|
|
192
|
+
*/
|
|
193
|
+
export enum OverlayAppearance {
|
|
194
|
+
/**
|
|
195
|
+
* Centered modal dialog with backdrop.
|
|
196
|
+
* Best for focused tasks: create forms, confirmations, destructive actions.
|
|
197
|
+
* Blocks underlying content visually. Escape or backdrop click dismisses.
|
|
198
|
+
*/
|
|
199
|
+
DIALOG = 'dialog',
|
|
200
|
+
/**
|
|
201
|
+
* Side or bottom drawer panel that slides in from an edge.
|
|
202
|
+
* Best for contextual content that benefits from seeing the underlying layout.
|
|
203
|
+
* Less disruptive than dialog. Common for detail views on mobile.
|
|
204
|
+
*/
|
|
205
|
+
SHEET = 'sheet',
|
|
206
|
+
/**
|
|
207
|
+
* Vaul-backed mobile drawer.
|
|
208
|
+
* Use when the navigation resolver should choose a drawer directly rather
|
|
209
|
+
* than relying on a dialog appearance plus mobileShape policy.
|
|
210
|
+
*/
|
|
211
|
+
DRAWER = 'drawer',
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Visual presentation for split transitions.
|
|
216
|
+
* Determines how adjacent zone content renders alongside the source zone.
|
|
217
|
+
*/
|
|
218
|
+
export enum SplitAppearance {
|
|
219
|
+
/**
|
|
220
|
+
* Standard vertical side panel.
|
|
221
|
+
* Content appears beside the source zone with a resizable divider.
|
|
222
|
+
* Most common for list-detail patterns.
|
|
223
|
+
*/
|
|
224
|
+
PANEL = 'panel',
|
|
225
|
+
/**
|
|
226
|
+
* Horizontal drawer (bottom panel).
|
|
227
|
+
* Content appears below the source zone.
|
|
228
|
+
* Used for companion panels like terminals, output logs, reference docs.
|
|
229
|
+
*/
|
|
230
|
+
DRAWER = 'drawer',
|
|
231
|
+
}
|
|
232
|
+
```
|