dashboard-tab-ui
Create or modify tabbed workflows in admin or vendor dashboards in the Mercur basic starter using stable tab structure, validation scope, and i18n-aware wizard conventions.
- License 许可
- MIT
- 所属仓库
- amoai-tech/mdeai
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 1
01 前言 Front Matter
- name
- dashboard-tab-ui
- description
- Create or modify tabbed workflows in admin or vendor dashboards in the Mercur basic starter using stable tab structure, validation scope, and i18n-aware wizard conventions.
03 SKILL.md 正文
Dashboard Tab UI
Use this skill when:
- adding a custom tab to a tabbed flow in admin or vendor
- extending a multi-step wizard
- reviewing tab layout, validation scope, or navigation behavior
Applies equally to admin and vendor dashboards.
Before introducing custom interactive UI inside a tab, apply medusa-ui-conformance.
Required component
Always use TabbedForm from @mercurjs/dashboard-shared — do NOT build custom tab navigation with ProgressTabs from @medusajs/ui directly.
TabbedForm API
TabbedForm handles internally: RouteFocusModal.Form, ProgressTabs in the header navbar, KeyboundForm, and a default footer with Cancel/Continue/Save.
Props
form—UseFormReturnfromreact-hook-formonSubmit— submit handler fromform.handleSubmit()isLoading(optional) — disables submit buttonfooter(optional) — custom footer render prop; omit to use the default
TabbedForm.Tab props
id(string, required) — unique tab identifierlabel(string, required) — display label in the tab barvalidationFields(FieldPath[], optional) — fields to validate on this tabisVisible((form) => boolean, optional) — dynamic tab visibility
Page structure
The create page wraps RouteFocusModal around the form component:
const CreatePage = () => (
<RouteFocusModal>
<CreateForm />
</RouteFocusModal>
);
export default CreatePage;
The form component renders TabbedForm directly — do NOT nest it inside another RouteFocusModal.Form:
const CreateForm = () => {
const { handleSuccess } = useRouteModal();
const form = useForm({ resolver: zodResolver(schema), defaultValues: { ... } });
const handleSubmit = form.handleSubmit(async (data) => {
handleSuccess("/entity-route");
});
return (
<TabbedForm form={form} onSubmit={handleSubmit}>
<TabbedForm.Tab id="general" label="General">
<div className="flex flex-col gap-y-4 p-8">
{/* Form.Field components */}
</div>
</TabbedForm.Tab>
</TabbedForm>
);
};
Known issue: validation blocks Continue
TabbedForm's internal onNext calls form.trigger() without arguments, which validates the entire form — not just the active tab's fields. Required fields on later tabs will prevent Continue from working.
Workaround: Only mark fields as required (.min(1)) if they are on the first tab. Use .optional() for fields on later tabs and validate at submit time if needed.
Hard rules
- Do not hardcode tab labels; use i18n-aware metadata.
- Do not put all fields into one flat tab without section structure.
- Do not build custom tab UI with
ProgressTabsdirectly — useTabbedForm. - Do not wrap
TabbedForminRouteFocusModal.Form— it does this internally. - Do not provide a custom
footerunless you need to change button labels — the default footer handles Cancel/Continue/Save correctly. - Do not add required zod validation to fields on tabs beyond the first (see known issue above).
- Do not break keyboard or submit behavior when adding a tab.
- Do not assume tabs are static if visibility depends on form state.
Preferred patterns
- Give each tab a single clear purpose.
- Keep a visible header (
Heading level="h2") and grouped sections inside each tab body. - Add
className="p-8"to the wrapping div inside eachTabbedForm.Tabfor consistent spacing. - Use
Form.Field/Form.Item/Form.Label/Form.Control/Form.ErrorMessagefrom@mercurjs/dashboard-shared. - Use
zodResolverwithreact-hook-formfor schema validation.
When to switch skills
- Page shell work ->
dashboard-page-ui - Form field work without wizard concerns ->
dashboard-form-ui
Verification
- confirm Continue navigates to the next tab (check that later-tab fields are not required in zod schema)
- confirm tab labels and content are translation-ready
- confirm dynamic visibility does not leave the flow in an invalid state
- run app build or lint after non-trivial tab work
04 同仓库更多 Skills
mde-pr-review-supabase
Use when reviewing MDE Supabase SQL, Auth and RLS changes in a pull request.
mde-pr-review-stripe
Use when reviewing MDE Stripe payments and webhooks changes in a pull request.
mde-pr-review-nextjs
Use when reviewing MDE Next.js App Router changes in a pull request.
mde-pr-review-mastra
Use when reviewing MDE Mastra agent, tool and workflow changes in a pull request.
mde-pr-review-maps
Use when reviewing MDE Google Maps and Places changes in a pull request.
mde-pr-review-copilotkit
Use when reviewing MDE CopilotKit and AG-UI changes in a pull request.