wtclaude
1d1350558b
The client twin of the server's declareSlot/registerExtension, and the same rule in both halves: core declares a slot, only core declares one, and at most one module fills it. Core renders <Slot name> and gets nothing back when the slot is unfilled, so an instance with no module installed renders exactly what it rendered before -- the same untouched-path guarantee withModuleNav makes. A slot is named for a PLACE, never for a meaning. Core supplies the position and the styling; the label, the target, the data and whether anything renders at all are the module's. The moment core types a slot by its content it has re-acquired the game semantics phase 3 exists to remove. This is the one place the client registry is not fail-open. An unknown slot, a non-component and a second fill all throw, matching checkExtensionShape server-side, because a dropped nav row costs a link the viewer can reach another way while a silently dropped extension is invisible to everyone including its author. A throw is always a programming error and never a race: core declares in its own bundle and every module chunk is a deferred script injected after it. Reading stays fail-safe -- undeclared and unfilled both read null -- and a filling component renders inside an error boundary. That asymmetry is where the client differs from the server: a module route that throws costs the module's own page, but an extension throws inside CORE's, and the whole reason core keeps ownership of that page is that it stays usable. Core decorates a slot through <Slot wrap>, not by asking whether it is filled. The obvious alternative is right about the unfilled case and wrong about the failed one -- the extension is filled, so the separator renders, and then the component throws into the boundary and leaves the separator behind on its own. wrap puts core's decoration inside the boundary where it shares the extension's fate. Found in a browser, with the footer's separator, which is the only place either could have been found. MODULE_API_VERSION 1.1.0 -> 1.2.0, both halves: the two state ONE version. Contract: docs/website/MODULE_API.md 3.7. Co-Authored-By: Claude <noreply@anthropic.com>
95 lines
4.0 KiB
JavaScript
95 lines
4.0 KiB
JavaScript
import { test, beforeEach } from 'node:test'
|
|
import assert from 'node:assert/strict'
|
|
|
|
import {
|
|
registry,
|
|
declareSlot,
|
|
registerExtension,
|
|
extensionFor,
|
|
registeredIds,
|
|
_reset,
|
|
} from '../src/modules/registry.js'
|
|
|
|
// Client extension slots (docs/website/MODULE_API.md §3.7) — the client twin of
|
|
// the server's declareSlot/registerExtension.
|
|
//
|
|
// The registry half only. `<Slot>` itself renders, and there is no DOM in this
|
|
// runner, so what it does with what these functions return — including the error
|
|
// boundary — is proved by the §7.7 browser smoke instead. Everything below is a
|
|
// rule that can be stated without rendering anything, and every one of them can
|
|
// be got wrong in a way a browser check would not obviously catch.
|
|
|
|
beforeEach(() => _reset())
|
|
|
|
const Fake = () => null
|
|
const Other = () => null
|
|
|
|
test('an unfilled slot reads as nothing', () => {
|
|
// The guarantee core's layouts rest on: place a slot, install no module, and
|
|
// the page renders what it rendered before.
|
|
declareSlot('site.footer.status')
|
|
assert.equal(extensionFor('site.footer.status'), null)
|
|
})
|
|
|
|
test('an undeclared slot reads as nothing rather than throwing', () => {
|
|
// Reading is core's side and stays fail-safe: a typo in a layout costs that
|
|
// spot, not the page. Only WRITING is strict, which is the next test.
|
|
assert.equal(extensionFor('nope'), null)
|
|
})
|
|
|
|
test('a module fills a declared slot and core reads it back', () => {
|
|
declareSlot('admin.users.detail')
|
|
registerExtension('uo', 'admin.users.detail', Fake)
|
|
assert.equal(extensionFor('admin.users.detail'), Fake)
|
|
assert.deepEqual(registeredIds(), ['uo'])
|
|
})
|
|
|
|
test('filling an unknown slot throws, naming the slot', () => {
|
|
// This is the one place the client registry is NOT fail-open, and the reason
|
|
// is asymmetry of consequence: a dropped nav row costs a link the viewer can
|
|
// reach another way, a silently dropped extension is invisible to everyone
|
|
// including its author. Declaration structurally precedes filling (§3.1), so
|
|
// this can only ever be a typo or a version skew.
|
|
assert.throws(() => registerExtension('uo', 'site.footer.sttaus', Fake), /unknown extension slot "site\.footer\.sttaus"/)
|
|
})
|
|
|
|
test('a non-component fill throws', () => {
|
|
declareSlot('site.footer.status')
|
|
assert.throws(() => registerExtension('uo', 'site.footer.status', { render: true }), /is not a component/)
|
|
})
|
|
|
|
test('a second module cannot take a filled slot, and the first keeps it', () => {
|
|
// Matches the server's rule exactly (registries.js): first fill wins, second
|
|
// is an error. The second half of the assertion is the one that matters — a
|
|
// rejected fill must not have half-replaced the incumbent.
|
|
declareSlot('admin.users.detail')
|
|
registerExtension('uo', 'admin.users.detail', Fake)
|
|
assert.throws(() => registerExtension('other', 'admin.users.detail', Other), /already filled by "uo"/)
|
|
assert.equal(extensionFor('admin.users.detail'), Fake)
|
|
})
|
|
|
|
test('declaring a slot twice throws', () => {
|
|
// Core-side programming error: two owners for one position means whichever
|
|
// module registered first wins by file order.
|
|
declareSlot('site.footer.status')
|
|
assert.throws(() => declareSlot('site.footer.status'), /already declared/)
|
|
})
|
|
|
|
test('core fills a slot through the same seam a module uses', () => {
|
|
// The client twin of registries.registerCore(). Core is a registrant with an
|
|
// id like any other, which is what makes slice 3 a deletion: the module
|
|
// registers the same slot and core drops its line.
|
|
declareSlot('site.footer.status')
|
|
registerExtension('core', 'site.footer.status', Fake)
|
|
assert.deepEqual(registeredIds(), ['core'])
|
|
})
|
|
|
|
test('declareSlot and extensionFor are not on the module-facing registry', () => {
|
|
// Declaring is core's alone (§3.7), and reading who filled a slot is core's
|
|
// too — the same line featureProviders() draws. registerExtension IS on the
|
|
// object, because filling is the whole point.
|
|
assert.equal(registry.declareSlot, undefined)
|
|
assert.equal(registry.extensionFor, undefined)
|
|
assert.equal(typeof registry.registerExtension, 'function')
|
|
})
|