docs(guides): add scenario cookbook (Solutions) + create-vs-edit-form example#2500
Merged
Merged
Conversation
… example Adds a goal-oriented "Solutions" docs section that answers "how do I solve business problem X" across objects/fields/forms/views/permissions/automation — the connective tissue missing between the per-feature guides and the schema references. Each recipe links to a runnable example and its decision record, and doubles as the few-shot corpus for AI authoring (ADR-0047 §3.5). Recipes: - create-vs-edit-form: derive both forms from one intent-tagged field set; hand-shape create only on real layout/flow divergence - field-grouping-and-order: field.group (semantic) vs form sections (layout) vs grid grouping (row aggregation) - role-based-interfaces: consumer App/page vs builder Studio surfaces - data-automation-interface-access: CRUD/FLS/RLS/capabilities/runAs mapping - public-data-collection: anonymous form with declaration-derived authz - approval-workflow: configure capability + runAs run-identity Showcase example backing recipe 1: - showcase_contact object: flat, grouped, intent-tagged field set - contact views: full grouped edit form + sparse formViews.create override bound via addRecord.formView Wires solutions into guides meta.json + index. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NvGeDWAo3rrjc3CQ8vmAac
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
added
the
skip-changeset
Claude
os-zhuang
marked this pull request as ready for review
July 1, 2026 04:54
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The mechanisms in this platform are all documented (schema references + per-feature metadata guides), but the connective tissue is missing: given a concrete business problem, which mechanisms to combine and why. This surfaced in a design conversation where every answer ("create form ≠ edit form", "where does field grouping live", "who sees automations") lived only in ADRs or in code — not discoverable as a how-to.
This PR adds a goal-oriented Solutions (Scenario Cookbook) docs section and seeds it with the first end-to-end recipe plus a runnable example. The recipes double as the few-shot corpus for AI authoring (ADR-0047 §3.5: "zero examples is why zero AI generations use these features").
Docs —
content/docs/guides/solutions/Each recipe follows a fixed shape: Scenario → Recommended solution → Why (→ ADR) → Runnable example → Anti-patterns.
create-vs-edit-form— derive both forms from one intent-tagged field set (required/readonly/defaultValue/group+ declaration order); hand-shapeformViews.createonly on real layout/flow divergence (ADR-0047).field-grouping-and-order— three different meanings of "group":field.group(semantic, on the object) vs formsections(layout) vs gridgrouping(row aggregation).role-based-interfaces— consumer App/page (interface mode) vs builder Studio surfaces; nav gating that hides rather than disables (ADR-0047/0066).data-automation-interface-access— map an access requirement onto object CRUD / FLS / RLS / capabilities / app gating / flowrunAs(ADR-0066/0057/0049).public-data-collection— anonymous form with declaration-derived authorization + field whitelist (ADR-0056).approval-workflow— themanage_metadataconfigure-capability +runAsrun-identity decision (ADR-0049/0066).Wired into
guides/meta.json(newSolutionssection) andguides/index.mdx(cards). All internal links resolve against the existing reference/guide tree.Example —
examples/app-showcaseBacks recipe 1:
objects/contact.object.ts—showcase_contact: flat, grouped (field.group), intent-tagged field set (required / readonly-derived / defaulted).views/contact.view.ts— full grouped editform(mirrors the auto-derived default) + a sparseformViews.createoverride, bound throughaddRecord.formView.objects/viewsindex files.Verification
@objectstack/specbuilds;examples/app-showcasetypecheck passes for the two newcontact.*files (remaining typecheck errors are unbuilt sibling workspace packages, pre-existing/environmental).meta.jsonfiles validated as JSON; new docs use existing frontmatter/Cards/Callout conventions.🤖 Generated with Claude Code
Generated by Claude Code