@asteby/metacore-runtime-react 46.4.0 → 47.0.0

package/src/document-form-dialog.tsx

@@ -0,0 +1,357 @@
+// DocumentFormDialog — alta guiada por tipo de documento (FAC-12, #1022).
+//
+// "Crear documento fiscal" era el mismo formulario genérico para factura, nota
+// de crédito, REP, global y traslado: los campos los dictaba el modelo, no el
+// tipo. Aquí el metadata (`document_forms`) o una prop declara los tipos; el
+// diálogo muestra tarjetas de tipo y, al elegir uno, SUS campos y (si lo declara)
+// el paso de renglones con el editor de renglones del SDK. Un solo tipo se salta
+// el selector; sin manifest el alta genérica sigue igual (DynamicCRUDPage decide).
+//
+// El SDK no hardcodea catálogos SAT: campos, valores fijos y el valor del tipo
+// vienen del manifest que sirve el kernel o el addon.
+import { useEffect, useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import {
+    Button,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+} from '@asteby/metacore-ui/primitives'
+import { Loader2 } from 'lucide-react'
+import { toast } from 'sonner'
+import { useApi } from './api-context'
+import { DynamicIcon } from './dynamic-icon'
+import { FieldCell, FieldGrid, FieldLabel } from './field-grid'
+import { FormErrorBanner } from './business/feedback'
+import {
+    DocumentLinesGrid,
+    type DocumentLinesGridProps,
+    type LineItemsColumn,
+} from './business/line-items-editor'
+import { serializeLineItems, validateLineItems, type LineItem } from './business/line-items'
+import {
+    actionErrorBannerMessage,
+    buildFieldDefaults,
+    renderField,
+} from './action-modal-dispatcher'
+import { extractFieldErrors, localizeFieldErrorMap } from './server-error'
+import { validateValues, bagHasErrors } from './validator'
+import { clearFieldErrorTree } from './field-validation-ui'
+import { emitRecordMutation } from './record-mutation-events'
+import { isLineItemsField, resolveWidget } from './dynamic-form-schema'
+import type {
+    ActionFieldDef,
+    DocumentFormLines,
+    DocumentFormsManifest,
+    DocumentFormType,
+    TableMetadata,
+} from './types'
+
+export interface DocumentFormDialogProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    /** Modelo en el que se da de alta (p. ej. `fiscal_documents`). */
+    model: string
+    /** Endpoint de alta. Default `/dynamic/<model>`. */
+    endpoint?: string
+    forms: DocumentFormsManifest
+    /** Tipo preseleccionado (se salta el selector). */
+    initialType?: string
+    /** Se llama con el registro creado. */
+    onSaved?: (record?: unknown) => void
+    /** Buscador de productos para el editor de renglones (mismo contrato que ProductPicker). */
+    searchProducts?: DocumentLinesGridProps['search']
+    /** Moneda ISO para el editor de renglones (default: la de la org). */
+    currency?: string
+}
+
+/** Manifest efectivo: la prop gana sobre el metadata; sin tipos devuelve undefined. */
+export function resolveDocumentForms(
+    metadata?: Pick<TableMetadata, 'document_forms'> | null,
+    override?: DocumentFormsManifest | null,
+): DocumentFormsManifest | undefined {
+    const m = override ?? metadata?.document_forms
+    return m && Array.isArray(m.types) && m.types.length > 0 ? m : undefined
+}
+
+function linesConfig(type: DocumentFormType, forms: DocumentFormsManifest): (DocumentFormLines & { field: string }) | undefined {
+    if (!type.lines) return undefined
+    const cfg: DocumentFormLines = type.lines === true ? {} : type.lines
+    return { ...cfg, field: cfg.field ?? forms.lines_field ?? 'lines' }
+}
+
+type Step = 'type' | 'fields' | 'lines'
+
+export function DocumentFormDialog({
+    open,
+    onOpenChange,
+    model,
+    endpoint,
+    forms,
+    initialType,
+    onSaved,
+    searchProducts,
+    currency,
+}: DocumentFormDialogProps) {
+    const { t, i18n } = useTranslation()
+    const api = useApi()
+    const types = forms.types
+    const single = types.length === 1 ? types[0] : undefined
+
+    const [typeKey, setTypeKey] = useState<string | null>(initialType ?? single?.key ?? null)
+    const [step, setStep] = useState<Step>(initialType || single ? 'fields' : 'type')
+    const [formData, setFormData] = useState<Record<string, any>>({})
+    const [lines, setLines] = useState<LineItem[]>([])
+    const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
+    const [serverLineErrors, setServerLineErrors] = useState<Record<string, string>>({})
+    const [formError, setFormError] = useState<string | undefined>()
+    const [saving, setSaving] = useState(false)
+
+    const type = useMemo(() => types.find((x) => x.key === typeKey) ?? null, [types, typeKey])
+    const lineCfg = type ? linesConfig(type, forms) : undefined
+
+    // Reset every time the dialog (re)opens.
+    useEffect(() => {
+        if (!open) return
+        const start = initialType ?? single?.key ?? null
+        setTypeKey(start)
+        setStep(start ? 'fields' : 'type')
+        setLines([])
+        setFieldErrors({})
+        setServerLineErrors({})
+        setFormError(undefined)
+    }, [open, initialType, single?.key])
+
+    // Seed field defaults for the chosen type.
+    useEffect(() => {
+        if (!type) return
+        setFormData({ ...buildFieldDefaults(type.fields, undefined), ...(type.defaults ?? {}) })
+        setFieldErrors({})
+        setFormError(undefined)
+    }, [type])
+
+    const updateField = (key: string, value: any) => {
+        setFormData((prev) => ({ ...prev, [key]: value }))
+        setFieldErrors((prev) => clearFieldErrorTree(prev, key))
+    }
+
+    const tl = (s: string) => t(s, { defaultValue: s })
+    const lang = i18n?.language
+
+    const chooseType = (k: string) => {
+        setTypeKey(k)
+        setStep('fields')
+    }
+
+    /** Validate the header fields; returns true when they pass. */
+    const validateHeader = (): boolean => {
+        if (!type) return false
+        const bag = validateValues(type.fields, formData)
+        if (!bagHasErrors(bag)) {
+            setFieldErrors({})
+            return true
+        }
+        const labels: Record<string, string> = {}
+        for (const f of type.fields) labels[f.key] = tl(f.label)
+        setFieldErrors(localizeFieldErrorMap(bag, t, { labels, language: lang }))
+        return false
+    }
+
+    const goNext = () => {
+        if (validateHeader()) setStep('lines')
+    }
+
+    const submit = async () => {
+        if (!type) return
+        if (!validateHeader()) {
+            setStep('fields')
+            return
+        }
+        if (lineCfg && (lineCfg.required ?? true)) {
+            const v = validateLineItems(lines, { requireItems: true })
+            if (!v.form && Object.keys(v.errors).length === 0) {
+                /* ok */
+            } else {
+                setServerLineErrors(v.errors)
+                setFormError(v.form ?? t('documentForm.lines_invalid', { defaultValue: 'Revisa los renglones del documento.' }))
+                setStep('lines')
+                return
+            }
+        }
+        setSaving(true)
+        setFormError(undefined)
+        try {
+            const payload: Record<string, unknown> = { ...(type.defaults ?? {}), ...formData }
+            if (forms.type_field) payload[forms.type_field] = type.value ?? type.key
+            if (lineCfg) payload[lineCfg.field] = serializeLineItems(lines)
+            const url = type.endpoint ?? endpoint ?? `/dynamic/${model}`
+            const res = await api.post(url, payload)
+            if (res.data?.success === false) {
+                handleError({ response: { data: res.data } })
+                return
+            }
+            toast.success(t('dynamic.create_success', { defaultValue: 'Registro creado correctamente' }))
+            emitRecordMutation(model, 'create')
+            onSaved?.(res.data?.data ?? res.data ?? undefined)
+            onOpenChange(false)
+        } catch (err) {
+            handleError(err)
+        } finally {
+            setSaving(false)
+        }
+    }
+
+    /** 422 → marks the fields and shows the banner INSIDE the dialog; stays open. */
+    const handleError = (err: unknown) => {
+        setFormError(actionErrorBannerMessage(err, type?.fields, t, lang))
+        const map = extractFieldErrors(err)
+        if (map) {
+            const labels: Record<string, string> = {}
+            for (const f of type?.fields ?? []) labels[f.key] = tl(f.label)
+            const localized = localizeFieldErrorMap(map, t, { labels, language: lang })
+            const header: Record<string, string> = {}
+            const lineErrs: Record<string, string> = {}
+            const prefix = lineCfg ? `${lineCfg.field}.` : null
+            for (const [k, v] of Object.entries(localized)) {
+                if (prefix && k.startsWith(prefix)) lineErrs[k.slice(prefix.length)] = v
+                else header[k] = v
+            }
+            setFieldErrors(header)
+            setServerLineErrors(lineErrs)
+        }
+    }
+
+    const canGoBackToTypes = types.length > 1 && !initialType
+    const stepLabel = (s: Step) =>
+        s === 'type'
+            ? t('documentForm.step_type', { defaultValue: 'Tipo de documento' })
+            : s === 'fields'
+              ? t('documentForm.step_data', { defaultValue: 'Datos' })
+              : tl(lineCfg?.title ?? 'Renglones')
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent
+                className="flex max-h-[90dvh] flex-col overflow-hidden sm:max-w-2xl"
+                style={{ maxHeight: '90dvh', ...(step === 'lines' ? { maxWidth: '980px', width: '95vw' } : {}) }}
+                data-slot="document-form-dialog"
+            >
+                <DialogHeader className="shrink-0">
+                    <DialogTitle>
+                        {type ? tl(type.label) : t('documentForm.title', { defaultValue: 'Nuevo documento' })}
+                    </DialogTitle>
+                    <DialogDescription>{stepLabel(step)}</DialogDescription>
+                </DialogHeader>
+
+                <div className="-mx-1 min-h-0 flex-1 space-y-3 overflow-y-auto px-1 py-3">
+                    <FormErrorBanner message={formError} />
+
+                    {step === 'type' && (
+                        <div role="radiogroup" className="grid gap-3 sm:grid-cols-2">
+                            {types.map((x) => (
+                                <button
+                                    key={x.key}
+                                    type="button"
+                                    role="radio"
+                                    aria-checked={x.key === typeKey}
+                                    data-type-card={x.key}
+                                    onClick={() => chooseType(x.key)}
+                                    className="flex items-start gap-3 rounded-lg border p-4 text-left transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                                >
+                                    {x.icon && <DynamicIcon name={x.icon} className="mt-0.5 size-5 shrink-0 text-primary" />}
+                                    <span>
+                                        <span className="block text-sm font-medium">{tl(x.label)}</span>
+                                        {x.description && (
+                                            <span className="block text-xs text-muted-foreground">{tl(x.description)}</span>
+                                        )}
+                                    </span>
+                                </button>
+                            ))}
+                        </div>
+                    )}
+
+                    {step === 'fields' && type && (
+                        <FieldGrid>
+                            {type.fields.map((field: ActionFieldDef) => {
+                                const fullWidth =
+                                    isLineItemsField(field) ||
+                                    resolveWidget(field) === 'textarea' ||
+                                    resolveWidget(field) === 'richtext'
+                                return (
+                                    <FieldCell key={field.key} fullWidth={fullWidth}>
+                                        <FieldLabel htmlFor={field.key} required={field.required}>
+                                            {tl(field.label)}
+                                        </FieldLabel>
+                                        {renderField(
+                                            field,
+                                            formData[field.key],
+                                            (v: any) => updateField(field.key, v),
+                                            formData,
+                                            undefined,
+                                            fieldErrors,
+                                        )}
+                                        {fieldErrors[field.key] && (
+                                            <p className="mt-1 text-xs text-destructive">{fieldErrors[field.key]}</p>
+                                        )}
+                                    </FieldCell>
+                                )
+                            })}
+                        </FieldGrid>
+                    )}
+
+                    {step === 'lines' && type && lineCfg && (
+                        <DocumentLinesGrid
+                            value={lines}
+                            onChange={(next) => {
+                                setLines(next)
+                                setServerLineErrors({})
+                            }}
+                            columns={(lineCfg.columns as LineItemsColumn[] | undefined) ?? ['discount', 'tax']}
+                            priceSource={lineCfg.price_source ?? 'sale'}
+                            serverErrors={serverLineErrors}
+                            search={searchProducts}
+                            currency={currency}
+                        />
+                    )}
+                </div>
+
+                <DialogFooter className="shrink-0">
+                    {step === 'type' ? (
+                        <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+                            {t('common.cancel', { defaultValue: 'Cancelar' })}
+                        </Button>
+                    ) : (
+                        <Button
+                            type="button"
+                            variant="outline"
+                            disabled={saving}
+                            onClick={() => {
+                                if (step === 'lines') setStep('fields')
+                                else if (canGoBackToTypes) setStep('type')
+                                else onOpenChange(false)
+                            }}
+                        >
+                            {step === 'fields' && !canGoBackToTypes
+                                ? t('common.cancel', { defaultValue: 'Cancelar' })
+                                : t('common.back', { defaultValue: 'Atrás' })}
+                        </Button>
+                    )}
+                    {step === 'fields' && type && lineCfg && (
+                        <Button type="button" onClick={goNext}>
+                            {t('common.next', { defaultValue: 'Siguiente' })}
+                        </Button>
+                    )}
+                    {((step === 'fields' && type && !lineCfg) || step === 'lines') && (
+                        <Button type="button" onClick={submit} disabled={saving}>
+                            {saving && <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />}
+                            {type?.submit_label ? tl(type.submit_label) : t('common.create', { defaultValue: 'Crear' })}
+                        </Button>
+                    )}
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    )
+}

package/src/dynamic-crud-page.tsx

@@ -33,13 +33,14 @@ import { useApi } from './api-context'
 import { useMetadataCache } from './metadata-cache'
 import { DynamicTable } from './dynamic-table'
 import { DynamicRecordDialog } from './dialogs/dynamic-record'
+import { DocumentFormDialog, resolveDocumentForms } from './document-form-dialog'
 import { ExportDialog } from './dialogs/export'
 import { ImportDialog } from './dialogs/import'
 import { getModelExtension } from './model-extension-registry'
 import { ModelActionToolbar } from './model-action-toolbar'
 import { resolveListPrimaryAction } from './list-primary-action'
 import { useCan, modelCapability } from './permissions-context'
-import type { TableMetadata } from './types'
+import type { DocumentFormsManifest, TableMetadata } from './types'
 
 export interface DynamicCRUDPageStrings {
     refresh?: string
@@ -90,6 +91,11 @@ export interface DynamicCRUDPageProps {
     classes?: DynamicCRUDPageClasses
     /** Fired after a create/import/refresh successfully reloads the table. */
     onChange?: () => void
+    /**
+     * Guided create by document type (FAC-12). Wins over `metadata.document_forms`;
+     * with neither, the generic record dialog is used as before.
+     */
+    documentForms?: DocumentFormsManifest
 }
 
 /**
@@ -112,6 +118,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
         toolbarExtras,
         classes,
         onChange,
+        documentForms,
     } = props
 
     const strings = { ...defaultStrings, ...(i18n ?? {}) }
@@ -186,6 +193,7 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
     const showImport = enableCRUD && !effectiveHideImport && can(modelCapability(model, 'import'))
     const showExport = !effectiveHideExport && can(modelCapability(model, 'export'))
     const showRefresh = !effectiveHideRefresh
+    const guidedForms = resolveDocumentForms(metadata, documentForms)
 
     const handleRefresh = useCallback(() => {
         setRefreshKey((k) => k + 1)
@@ -274,7 +282,18 @@ export function DynamicCRUDPage(props: DynamicCRUDPageProps) {
                 </div>
             </div>
 
-            {showCreate && (
+            {showCreate && guidedForms && (
+                <DocumentFormDialog
+                    open={openCreate}
+                    onOpenChange={setOpenCreate}
+                    model={model}
+                    endpoint={dataEndpoint}
+                    forms={guidedForms}
+                    onSaved={handleRefresh}
+                />
+            )}
+
+            {showCreate && !guidedForms && (
                 <DynamicRecordDialog
                     open={openCreate}
                     onOpenChange={setOpenCreate}

package/src/dynamic-kanban.tsx

@@ -152,6 +152,7 @@ import { useFlipAnimation } from './use-flip-animation'
 import { PortalDragOverlay } from './portal-drag-overlay'
 import { objectLabel } from './dynamic-relation-helpers'
 import { useMetadataCache } from './metadata-cache'
+import { useRecordMutationTick } from './use-record-mutation-tick'
 import { useOptionsResolver } from './use-options-resolver'
 import { ActivityValueRenderer } from './activity-value-renderer'
 import { DynamicIcon } from './dynamic-icon'
@@ -923,6 +924,7 @@ function DynamicKanbanBoard({
     // Realtime refetch (opt-in) — debounced counter bumped by DATA_EVENTs for
     // this model; folded into the board refetch effect next to refreshTrigger.
     const realtimeDefault = useRealtimeDefault()
+    const mutationTick = useRecordMutationTick(model)
     const realtimeTick = useRealtimeTick({
         models: [model],
         enabled: realtimeProp ?? realtimeDefault,
@@ -1339,7 +1341,7 @@ function DynamicKanbanBoard({
         return () => clearTimeout(handle)
         // realtimeTick: data events for this model (see the `realtime` prop).
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [fetchData, metadata, refreshTrigger, realtimeTick])
+    }, [fetchData, metadata, refreshTrigger, realtimeTick, mutationTick])
 
     // Filterable fields for the toolbar, in metadata order (explicit filters
     // first, then filterable columns), each labeled from its metadata source.

package/src/dynamic-table.tsx

@@ -66,6 +66,7 @@ import { Inbox, Download, Upload, Trash2 } from 'lucide-react'
 import { toast } from 'sonner'
 import { Progress } from './dialogs/_primitives'
 import { useMetadataCache } from './metadata-cache'
+import { useRecordMutationTick } from './use-record-mutation-tick'
 import { useApi, useCurrentBranch } from './api-context'
 import { useReasonPrompt } from './reason-prompt'
 import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-shim'
@@ -295,6 +296,9 @@ export function DynamicTable({
     // OrgRuntimeProvider (without it, money fell back to USD).
     const orgTimeZone = useTimeZone()
     const orgCurrency = useCurrency()
+    // Bumps when a dialog/modal anywhere creates, edits or deletes a record of
+    // this model, so the list reloads without the caller wiring refreshTrigger.
+    const mutationTick = useRecordMutationTick(model)
     const timeZone = timeZoneProp ?? orgTimeZone
     const currency = currencyProp ?? orgCurrency
     // The explicit `pagination` prop wins; the legacy `infiniteScroll` boolean
@@ -917,7 +921,7 @@ export function DynamicTable({
         } finally {
             setLoadingData(false)
         }
-    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, endpoint, currentBranch?.id, api, enableUrlSync, relationInclude])
+    }, [model, metadata, pagination, buildFilterParams, refreshTrigger, mutationTick, endpoint, currentBranch?.id, api, enableUrlSync, relationInclude])
 
     // Columns whose metadata opts into a footer total (display_config.aggregate
     // → styleConfig.aggregate). When empty, no footer row is rendered and no
@@ -1098,7 +1102,7 @@ export function DynamicTable({
         // deps). Without it the comment above lied: infinite lists silently
         // failed to reload after a create ("a veces no recarga la tabla").
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [infiniteScroll, metadata, filterSignature, refreshTrigger])
+    }, [infiniteScroll, metadata, filterSignature, refreshTrigger, mutationTick])
 
     const handleRefresh = useCallback(() => {
         // Infinite mode owns its own list: refresh reloads page 1 and drops the

package/src/index.ts

@@ -196,6 +196,34 @@ export {
     type ListActionRef,
     type CreateMode,
 } from './list-primary-action'
+export {
+    emitRecordMutation,
+    subscribeRecordMutations,
+    RECORD_MUTATION_EVENT,
+    type RecordMutationKind,
+    type RecordMutationDetail,
+} from './record-mutation-events'
+export {
+    DocumentFormDialog,
+    resolveDocumentForms,
+    type DocumentFormDialogProps,
+} from './document-form-dialog'
+export {
+    modelFromNavUrl,
+    capabilityForNavItem,
+    isNavItemAllowed,
+    useNavItemVisible,
+    type NavLeafLike,
+} from './nav-permissions'
+export {
+    CfdiStampPanel,
+    CfdiStampResultDialog,
+    extractStampResult,
+    type CfdiStampResult,
+    type CfdiStampPanelProps,
+    type CfdiStampResultDialogProps,
+} from './cfdi-stamp-panel'
+export { useRecordMutationTick } from './use-record-mutation-tick'
 export * from './addon-loader'
 export {
     PURGE_ADDON_MESSAGE,

package/src/nav-permissions.ts

@@ -0,0 +1,58 @@
+// nav-permissions — the sidebar follows the role's EFFECTIVE permissions
+// (PIT-044). Before, every installed addon's entries were listed for every
+// role and only failed with a 403 after the click.
+//
+// Rules (same capability vocabulary as useCan/gateTableMetadata):
+//   - no <PermissionsProvider> mounted, or isAdmin / "*"  -> nothing hidden
+//     (useCan() is always-true then, so the predicate is a no-op);
+//   - an entry with an explicit `requires` capability     -> can(requires);
+//   - an entry pointing at a model screen (`/m/<model>`)  -> can('<model>.index');
+//   - any other entry (custom pages, activity, settings…) -> kept. Those are
+//     gated by the backend / the host's own `requires`, never guessed here.
+import { useCallback } from 'react'
+import { modelCapability, useCan, usePermissionsActive, type CanFn } from './permissions-context'
+
+/** Minimal structural shape of a sidebar leaf (matches `@asteby/metacore-ui` NavLinkItem). */
+export interface NavLeafLike {
+    url: string
+    requires?: string
+}
+
+const MODEL_URL_RE = /^\/(?:app\/)?m\/([^/?#]+)/i
+
+/** Model key of a `/m/<model>` url, or undefined for any other route. */
+export function modelFromNavUrl(url: string | undefined): string | undefined {
+    if (!url) return undefined
+    const m = MODEL_URL_RE.exec(url)
+    if (!m) return undefined
+    try {
+        return decodeURIComponent(m[1])
+    } catch {
+        return m[1]
+    }
+}
+
+/** Capability a leaf needs, or undefined when it is not gated by the SDK. */
+export function capabilityForNavItem(item: NavLeafLike): string | undefined {
+    if (item.requires) return item.requires
+    const model = modelFromNavUrl(item.url)
+    return model ? modelCapability(model, 'index') : undefined
+}
+
+/** Pure visibility predicate for a leaf given a capability checker. */
+export function isNavItemAllowed(item: NavLeafLike, can: CanFn): boolean {
+    const cap = capabilityForNavItem(item)
+    return cap ? can(cap) : true
+}
+
+/**
+ * Hook for the host's sidebar: returns a predicate for `<AppSidebar
+ * isItemVisible>` / `filterNavGroups`, or `undefined` when permission gating
+ * is not active (nothing to filter).
+ */
+export function useNavItemVisible(): ((item: NavLeafLike) => boolean) | undefined {
+    const can = useCan()
+    const active = usePermissionsActive()
+    const predicate = useCallback((item: NavLeafLike) => isNavItemAllowed(item, can), [can])
+    return active ? predicate : undefined
+}

package/src/navigation-builder.tsx

@@ -1,6 +1,7 @@
 // NavigationBuilder — merges a host's base sidebar with `manifest.navigation`
 // contributions from every loaded addon. Pure function + a React hook.
 import { useMemo } from 'react'
+import { useCan, type CanFn } from './permissions-context'
 
 export interface NavItem {
     key: string
@@ -59,8 +60,33 @@ export function mergeNavigation(base: NavItem[], contributions: AddonNavigationC
         .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
 }
 
+/**
+ * Drops items whose `requires` capability the user lacks (PIT-044). A parent
+ * left without children is dropped too, unless it links somewhere itself.
+ */
+export function filterNavigationByCapability(items: NavItem[], can: CanFn): NavItem[] {
+    const out: NavItem[] = []
+    for (const item of items) {
+        if (item.requires && !can(item.requires)) continue
+        if (item.children) {
+            const children = filterNavigationByCapability(item.children, can)
+            if (children.length === 0 && item.children.length > 0 && !item.to) continue
+            out.push({ ...item, children })
+        } else {
+            out.push(item)
+        }
+    }
+    return out
+}
+
 export function useNavigation(base: NavItem[], contributions: AddonNavigationContribution[]): NavItem[] {
-    return useMemo(() => mergeNavigation(base, contributions), [base, contributions])
+    // useCan() allows everything without a <PermissionsProvider>, so hosts that
+    // never opt in keep the full tree.
+    const can = useCan()
+    return useMemo(
+        () => filterNavigationByCapability(mergeNavigation(base, contributions), can),
+        [base, contributions, can],
+    )
 }
 
 export interface NavigationBuilderProps {