API Reference
Fabricate exposes its API through two Foundry globals:
game.fabricate. The main Fabricate instance with service accessors and a quickcraft()helper.globalThis.fabricate(alias:fabricate). Convenience functions for macros.game.fabricate.api. Constructor references for all public classes, plus public constants (HOOKS— the published hook names — andcompanion, the versioned companion contract).game.fabricate.api.ui. The published UI components a companion renders into an element it owns.
All APIs except the two extension-registration seams are available after the fabricate.ready hook fires. api.ui exists once Fabricate’s own init listener has run (read it in setup or later, never in your own init), and its mount throws until the fabricate.ready hook has fired:
Hooks.on('fabricate.ready', () => {
const recipeManager = game.fabricate.getRecipeManager();
// API is now safe to use
});
Do not call Fabricate APIs before the
fabricate.readyhook. The module initialises during Foundry’sreadyhook, and services are not available until initialisation completes. A companion’s extension registrations are the exceptions, and there are two of them. Register each during the companion’sinitcallback, as described in Manager Navigation Extension and Player Navigation Extension.api.uiexists once Fabricate’s owninitlistener has run, but itsmountthrows untilfabricate.readyfires; a companion’s own Foundryreadycallback runs while Fabricate is still initialising, so mount fromfabricate.readyor later.
Quick Reference
Services And Runtime Methods
game.fabricate.getRecipeManager() // Recipe CRUD and queries
game.fabricate.getCraftingEngine() // Execute crafting
game.fabricate.getCraftingSystemManager() // System and component CRUD
game.fabricate.getCraftingRunManager() // Multi-step run management
game.fabricate.listCraftingForActor({ rememberedActorId, componentSourceActorIds, presentTools }) // Player-visible crafting listing (summary phase)
game.fabricate.hydrateCraftingRecipe({ recipeId, actorId, componentSourceActorIds, presentTools }) // Exact detail model for one recipe (detail phase)
game.fabricate.craftRecipe({ actorId, recipeId, ingredientSetId, componentSourceActorIds, interactive, presentTools }) // Craft the selected recipe
game.fabricate.salvageComponent({ actorId, systemId, componentId, interactive }) // Salvage one owned component
game.fabricate.salvageComponents({ actorId, targets, interactive, onProgress }) // Salvage many owned components in one run
game.fabricate.destroyComponents({ actorId, targets, onProgress }) // Permanently destroy many owned components in one run
game.fabricate.getGatheringEnvironmentStore() // Gathering environment persistence
game.fabricate.getGatheringRunManager() // Gathering run persistence
game.fabricate.getGatheringGateAndCheckEvaluator() // Gathering gate/check evaluation
game.fabricate.getGatheringRichStateService() // Gathering rich-state internals
game.fabricate.listGatheringForActor({ actor, presentTools }) // Player-visible gathering listing
game.fabricate.startGatheringAttempt({ actor, environmentId, taskId, presentTools }) // Start gathering
game.fabricate.getGatheringDropBreakdown({ environmentId, taskId }) // Task drop preview data
game.fabricate.listAlchemyForActor({ actorId, craftingSystemId }) // Leak-safe player alchemy listing
game.fabricate.submitAlchemyAttempt({ actorId, craftingSystemId, submittedComponentIds, presentTools }) // Brew an alchemy attempt
game.fabricate.getSelectedAlchemySystemId() // Persisted last-selected alchemy system id
game.fabricate.setSelectedAlchemySystemId(id) // Persist the last-selected alchemy system id
game.fabricate.listSelectableActors() // Player-character actors for the actor-selection bar
game.fabricate.listCuratedIcons() // Fabricate's curated Font Awesome icon vocabulary
game.fabricate.findCuratedIcon(name) // Resolve one icon name (or alias) against that vocabulary
game.fabricate.getSelectedGatheringActorId() // Persisted remembered gathering actor id
game.fabricate.setSelectedGatheringActorId(id) // Persist the remembered gathering actor id
game.fabricate.getHideUnavailableEnvironments() // Player "hide unavailable environments" toggle (per client/device)
game.fabricate.setHideUnavailableEnvironments(value) // Persist that toggle (per client/device)
game.fabricate.getGatheringConditions() // Global current gathering weather/time and vocabularies
game.fabricate.setGatheringWeather(weatherTag) // GM-only gathering weather update
game.fabricate.setGatheringTimeOfDay(timeOfDayTag) // GM-only gathering time update
game.fabricate.setGatheringConditions({ weather, timeOfDay }) // GM-only global conditions update
game.fabricate.getGatheringPartyStore() // Fabricate-managed gathering parties (world-level)
game.fabricate.getGatheringRealmStore() // Per-system gathering realm CRUD and settings (was getGatheringRegionStore — deprecated alias kept)
game.fabricate.getGatheringLocationService() // Party current-realm resolution
game.fabricate.getGatheringLocationForActor({ actor, systemId }) // Redaction-safe current-realm summary
game.fabricate.setGatheringPartyRealmOverride({ partyId, systemId, realmIds }) // GM-only realm override (was setGatheringPartyRegionOverride)
game.fabricate.clearGatheringPartyRealmOverride({ partyId, systemId }) // GM-only override clear
game.fabricate.revealGatheringRealmForActor({ actor, systemId, realmId }) // GM-only discovery reveal
game.fabricate.hideGatheringRealmForActor({ actor, systemId, realmId }) // GM-only discovery hide
game.fabricate.getGatheringEconomy({ systemId }) // Gathering economy block
game.fabricate.setGatheringEconomy({ systemId, economy }) // GM-only economy update
game.fabricate.getRecipeVisibilityService() // Visibility and knowledge
game.fabricate.resetActorKnowledge({ actorId, systemId, freeLearnBudget }) // GM-only reset of one actor's learned recipes (one system, or all systems when systemId is null)
game.fabricate.grantRecipeKnowledge({ actorId, recipeId, grantedBy }) // GM-only recipe-knowledge grant, no owned book required (companion contract)
game.fabricate.checkAffordability({ actorId, unitId, amount }) // GM-only world-scoped affordability answer (companion contract)
game.fabricate.getCurrencyConfigStore() // World currency configuration store (null before ready)
game.fabricate.getActorPropertyCoinSpender() // Coin spender for the actorProperty strategy (null before ready)
game.fabricate.getActorInventoryCoinSpender() // Coin spender for the actorInventory strategy (null before ready)
game.fabricate.getResolutionModeService() // Mode validation and resolution
Global Macro Helpers
fabricate.createSimpleRecipe(name, ingredients, result)
fabricate.craft(actor, recipeId, options)
fabricate.listRecipes(filters)
fabricate.deleteRecipe(recipeId)
fabricate.getAvailableRecipes(actorOrActors)
fabricate.openRecipeManager()
fabricate.listCraftingSystems()
fabricate.openRecipeManager() returns a promise that resolves once the manager’s code has loaded and the window has been asked to open. It carries no GM gate itself, so calling it as a non-GM user still resolves the promise, but the manager shows the user a GM-only notification instead of opening. If the browser is running a stale, cached copy of Fabricate and the manager’s code cannot be loaded, it notifies the user with a message telling them to reload, and the returned promise still rejects with the original error so a macro’s await sees the failure.
Class Constructors
const {
Recipe, Ingredient, IngredientGroup,
RecipeManager, CraftingEngine,
getFabricateAppClass,
loadCraftingSystemManagerAppClass, getCraftingSystemManagerAppClass,
CraftingSystemManager,
CraftingRunManager, SalvageRunManager,
GatheringEnvironmentStore, GatheringRunManager,
GatheringRealmStore, GatheringPartyStore,
GatheringLocationService,
GatheringGateAndCheckEvaluator, GatheringEngine,
RecipeVisibilityService, ResolutionModeService,
SignatureValidator,
CompendiumImporter, CraftingSystemExporter
} = game.fabricate.api;
The GM crafting-system-manager app is loaded from a separate on-demand chunk so non-GM players never download it. Open it programmatically through the async accessor, which loads (and registers) the class the first time it is called, then caches it:
const AppClass = await game.fabricate.api.loadCraftingSystemManagerAppClass();
AppClass.show();
The synchronous getCraftingSystemManagerAppClass() still exists for backward compatibility, but it now throws until the manager has been opened at least once (i.e. until loadCraftingSystemManagerAppClass(), the header button, or fabricate.openRecipeManager() has loaded the chunk). Prefer the async accessor.
Called directly like this, loadCraftingSystemManagerAppClass() does not notify the user on a failed load. It is a raw accessor, so a caller that awaits it is responsible for reporting the failure to its own user. fabricate.openRecipeManager() is the wrapped equivalent that does notify.
Crafting Runtime Facade
Use these public game.fabricate methods when macros or integrations need to browse or craft for the current user. They back the player Crafting tab and inject the current Foundry user as the viewer before delegating to runtime internals. Browsing and crafting are split into two phases so the browse cost tracks the page rather than the whole recipe corpus.
Hooks.once('fabricate.ready', async () => {
const listing = game.fabricate.listCraftingForActor();
const row = listing.summaries[0];
if (!row) return;
// Exact per-recipe model, fetched only for the row the player opened.
const detail = game.fabricate.hydrateCraftingRecipe({ recipeId: row.id });
if (!detail) return; // Gone, disabled, blocked, or no longer visible.
const outcome = await game.fabricate.craftRecipe({ recipeId: row.id });
console.log(outcome.success ? 'Crafted' : `Failed: ${outcome.message}`);
});
listCraftingForActor({ rememberedActorId, componentSourceActorIds, presentTools })is the summary phase. It returns cheap, redaction-safe summary rows for every recipe the viewer may see, projected without running exact craftability against the whole corpus.rememberedActorIdandcomponentSourceActorIdsdefault to the persisted crafting selections when omitted. Each row’s material verdict (itsbrowseStatus) and the listing’s owncounts.availableare optimistic — an upper bound read from an indexed availability snapshot, not exact evaluation. A recipe whose ingredient sets contend for the same held stacks can read available in the list and still refuse once hydrated or crafted. A row reporting unavailable is definitive; the optimism only ever runs in the makeable direction. A recipe whose required Tools are not held — or supplied bypresentTools, the Active Canvas Tool’s payload — never reads available.hydrateCraftingRecipe({ recipeId, actorId, componentSourceActorIds, presentTools })is the detail phase. It returns the exact rich model — per-set craftability, ingredient assignment, check resolution, outcome tiers, steps and progressive stages — for the one recipe the player has opened.recipeIdarrives from a client and is not trusted: the recipe’s visibility, itsenabledflag, and its crafting system’s blocked state are all re-evaluated from scratch rather than taken from the summary pass. The call returnsnull, never throws, when the recipe does not exist, is disabled, sits in a blocked crafting system, or the viewer may not see it. An id is not a permission.presentToolsis optional and defaults tonull. It has the shape{ systemId, componentIds, toolIds }, and the player app supplies it from the active canvas Tool station so the station’s Tool counts as present for recipes in that station’s crafting system only. Passnullor omit it when there is no station.craftRecipe({ actorId, recipeId, ingredientSetId, ingredientEssenceAllocation, componentSourceActorIds, interactive, presentTools })executes the attempt, delegating to the same pipeline documented in CraftingEngine.presentToolsis the same optional station payload described forhydrateCraftingRecipe, and a borrowed station Tool is never worn down or used up. It applies to this call only: the active GM checks it against each command the craft sends and never stores it on the run, so a later step needs the station again. Exact craft-time validation is always authoritative, independent of what either listing phase reported.
Gathering Runtime Facade
Use the public game.fabricate methods when macros or integrations need to list or start gathering for the current user. The raw gathering engine is not exposed as a service accessor. These facade methods inject the current Foundry user as the viewer before delegating to runtime internals.
Hooks.once('fabricate.ready', async () => {
const actor = game.user.character;
const listing = await game.fabricate.listGatheringForActor({ actor });
const environment = listing.environments[0];
const task = environment?.tasks?.[0];
if (environment && task?.attemptable) {
await game.fabricate.startGatheringAttempt({
actor,
environmentId: environment.id,
taskId: task.id
});
}
});
listGatheringForActor returns the current browsing state plus activeRuns and recent history for the selected actor. Those run lists are retained even when no environment/task rows are currently browseable because the actor is blocked, the environment list is empty, or visibility gates hide all tasks. For non-GM blind or missing-environment rows, the runtime redacts task IDs, result details, tool details, diagnostics, and check internals.
When rememberedActorId is omitted from listGatheringForActor options, it defaults to the persisted last-gathering selection (getSelectedGatheringActorId()), so a fresh listing honors the remembered actor. Passing an explicit rememberedActorId always overrides that default. This includes an explicit null, which forces no remembered actor.
listGatheringForActor and startGatheringAttempt also accept presentTools, the optional station payload described for hydrateCraftingRecipe. A Tool the station supplies counts as present for the attempt’s start and, when the attempt is ready, for the execute the same call sends; a timed attempt needs the station again when it is resolved from the Journal.
Alchemy Runtime Facade
Use these public game.fabricate methods when macros or integrations need to list or brew alchemy for the current user. They back the player Alchemy Workbench and inject the current Foundry user as the viewer before delegating to runtime internals.
Hooks.once('fabricate.ready', async () => {
const actorId = game.user.character?.id;
const craftingSystemId = game.fabricate.getSelectedAlchemySystemId(); // '' when unset
// Leak-safe listing: learned recipes, owned components, and the COUNT of
// undiscovered recipes only. Undiscovered names, signatures, and results are
// never returned.
const listing = game.fabricate.listAlchemyForActor({ actorId, craftingSystemId });
// Brew a combination: one component id per placed unit (a stack of N appears N times).
const submittedComponentIds = listing.recipes[0]?.concrete
? Object.entries(listing.recipes[0].concrete).flatMap(([id, qty]) => Array(qty).fill(id))
: [];
if (submittedComponentIds.length > 0) {
await game.fabricate.submitAlchemyAttempt({
actorId,
craftingSystemId,
submittedComponentIds,
interactive: true
});
}
});
listAlchemyForActor({ actorId, craftingSystemId, componentSourceActorIds })returns the leak-safe alchemy listing model for the resolved crafting actor, scoped to the chosen alchemy (crafting) system. It is owner-scoped through the same gate as crafting, so a non-owner viewer receives a denied, empty listing rather than another user’s inventory or fizzle memory. A GM sees every enabled recipe as known.actorIdandcomponentSourceActorIdsdefault to the persisted crafting selections when omitted.submitAlchemyAttempt({ actorId, craftingSystemId, submittedComponentIds, componentSourceActorIds, interactive, presentTools })brews the submitted components as an attempt for the resolved actor. It is owner-scoped likelistAlchemyForActorand delegates to the authoritative engine, which matches the submission against all enabled recipes in the system, known and undiscovered alike. On a match the recipe is discovered when Learn on Craft is on, and every submitted unit is spent when the brew starts, drawn only from the submitted items. A matched brew that can resolve now resolves in this call throughexecutePublicBrew, ascraftRecipedoes throughexecutePublicCraft; a time-gated brew starts and returns the run for later completion in the Journal. If the execute is cancelled or refused after the start, the reply still carries the started run’srunId; its units are already spent, and the run can be finished or cancelled from the Journal. A match the submitted units cannot fund is refused with nothing consumed. The system’s alchemy check mode decides the result:nonealways produces the success set, asimplecheck produces the success set on a pass and the reserved failure set on a fail, and atieredcheck routes to the result set for the rolled outcome tier. A failedsimplecheck still counts as a match, so it discovers the recipe, and its spent units are kept, or returned when Consume on Fail is off. It produces the failure set when one is authored with results and the failure-result policy permits; otherwise nothing is produced. The reply carriesdisposition: 'failed', withcreatedResultUuidslisting any awarded items. Otherwise the attempt fizzles with no check and no roll, consuming the components only when the system’s Consume on Fail setting is on.interactiveprompts a roll on a matched brew insimpleortieredcheck mode, and defaults tofalsefor macros and automation, so it never triggers a roll on the fizzle path.presentToolsis the optional station payload described forhydrateCraftingRecipe, so a matched recipe’s Tool supplied by the station counts as present for the brew’s start and its same-call execute, as forcraftRecipe; a time-gated brew needs the station again when it is resolved from the Journal, because a crafting Journal command carries the station.getSelectedAlchemySystemId()reads the persisted last-selected alchemy system from thefabricate.lastAlchemySystemclient setting, returning''when unset.setSelectedAlchemySystemId(id)persists the selection to that same client setting.
The fabricate.lastAlchemySystem setting is scope: 'client', so the choice is remembered per client/device, not per user account.
Salvage Runtime Facade
salvageComponent({ actorId, systemId, componentId, interactive }) salvages one owned component. It backs the player Inventory tab’s Salvage panel and is the supported entry point for macros and integrations.
Hooks.once('fabricate.ready', async () => {
const actorId = game.user.character?.id;
const systemId = game.fabricate.listCraftingSystems()[0]?.id;
const outcome = await game.fabricate.salvageComponent({
actorId,
systemId,
componentId: 'my-component-id'
});
if (outcome.cancelled) return; // The player dismissed the roll prompt.
if (!outcome.success) {
console.log(`Salvage failed: ${outcome.message}`);
} else if (outcome.results === null) {
console.log(`Salvage started: ${outcome.message}`); // Time-gated run.
} else {
console.log(`Recovered: ${outcome.results.map((item) => item.name).join(', ')}`);
}
});
It takes an actorId, never an actorUuid. The facade resolves that id through the same ownership gate as craftRecipe, and that gate is the only ownership check on the salvage path. CraftingEngine.salvage performs none of its own: it resolves the UUID it is handed and mutates that actor’s items directly. Passing a uuid straight to the engine therefore bypasses the gate, and a stale or foreign uuid throws at the server rather than returning a message. actorId defaults to the persisted last-crafting selection, and an unresolved actor returns { success: false, results: null, message: 'No crafting actor selected' }.
interactive prompts the player to roll (with Advantage / Normal / Disadvantage where the formula allows it, a situational-bonus field, and a roll-mode picker) and posts the roll to chat so Dice So Nice animates it. It defaults to false, so macros and automation stay silent. The player Inventory tab passes true.
The returned object has four shapes, and cancelled is distinct from a failure:
| Outcome | Shape | Meaning |
|---|---|---|
| Cancelled | { success: false, cancelled: true, results: null } | The player dismissed the roll prompt. Nothing was consumed, no tool broke, and any run created by the call was discarded. Do not report this as an error. |
| Started | { success: true, results: null, message } | The component has a time requirement, so a run started and awarded nothing yet. It settles as world time advances. |
| Awarded | { success: true, results: [...], salvageRun } | The salvage resolved and created the result items. |
| Failed | { success: false, message } | An ordinary failure: actor, system or component not found, salvage disabled, validation failed, or the mode requires a roll formula the GM has not authored. |
The engine returns these rather than throwing, so ordinary failures need no try/catch.
Do not thread a result order into this call. For a progressive salvage, the engine captures the player’s standing order (salvage:<systemId>:<componentId> in fabricate.progressiveResultOrder) onto the run record when the run starts, and reads it back at award time. A caller that wants a different order writes that setting first and lets the capture happen.
Bulk Salvage & Destroy Runtime Facade
salvageComponents({ actorId, targets, interactive, onProgress }) salvages many owned components in one gesture, and destroyComponents({ actorId, targets, onProgress }) permanently destroys many owned components (whole stacks) in one gesture. Both back the player Inventory tab’s bulk panel and are the supported entry points for macros and integrations that need to act on several components at once.
Hooks.once('fabricate.ready', async () => {
const actorId = game.user.character?.id;
const systemId = game.fabricate.listCraftingSystems()[0]?.id;
const targets = [
{ systemId, componentId: 'iron-ore' },
{ systemId, componentId: 'oak-branch' }
];
const outcome = await game.fabricate.salvageComponents({ actorId, targets });
if (outcome.cancelled) {
console.log('The batch roll prompt was dismissed; nothing ran.');
} else {
for (const item of outcome.items) {
console.log(`${item.name}: ${item.outcome}`);
}
}
});
Neither facade takes an actor UUID, at any nesting level. Each entry in targets may carry its own actorId, falling back to the call’s own actorId when omitted, and either way that id is resolved through the same ownership gate salvageComponent uses. A target whose actor cannot be resolved is never retargeted onto a different actor and never thrown as an exception. It becomes a row in the returned items[] carrying outcome: 'notPermitted', and every other target in the same call still runs.
targets is Array<{ actorId?: string, systemId: string, componentId: string }>, in the order the caller wants them run. A single call accepts at most 25 targets. A target beyond that limit is refused before anything runs, reported as outcome: 'skipped' with skipReason: 'bulkLimit'.
interactive defaults to true for salvageComponents, unlike salvageComponent’s default of false, because this facade exists for a player gesture rather than automation. It opens at most ONE roll prompt for the whole batch, setting a single situational bonus, roll mode, and advantage choice that is applied to every roll in the run. Every target still rolls its own check against its own crafting system. If the player dismisses that prompt, the call returns { cancelled: true, items: [], counts: {...}, posted: false } immediately. Nothing was queued, consumed, or rolled. destroyComponents opens no prompt at all. The caller owns the confirmation, and this facade executes against the snapshot the confirmation named.
onProgress, when supplied, is called (completed, total) after each target resolves. total counts only the targets the gate accepted, so a run containing a notPermitted row finishes below the caller’s own targets.length. A listener that throws is caught and logged, and it never breaks the run.
salvageComponents Outcomes
salvageComponents returns { cancelled, items, counts, posted }. Each row of items carries { actorId, actorName, systemId, componentId, name, img, outcome, skipReason, rollValue, tierStep, message, results, consumed, tools }, in the caller’s own target order.
| Outcome | Meaning |
|---|---|
succeeded | The check succeeded, or none was required. Usually this creates result items, but a routed/progressive success tier authored with no results succeeds and awards nothing, so read results.length rather than the outcome alone to know what arrived. |
failed | The check failed outright: a rolled failure tier, or a total that matches no authored range. Not enough units and a required tool unavailable are the pre-check failure reasons. A success tier that awarded nothing is succeeded, never failed. |
waiting | The component has a time requirement, so a run started and awarded nothing yet. |
misconfigured | The mode requires a roll formula the GM has not authored. |
skipped | Refused before the engine was called; see skipReason below. |
notPermitted | The target named no actor this call could resolve. |
error | The engine call threw; message carries the error text. |
A skipped row also carries a skipReason: unknownSystem, featureDisabled (the system’s Salvage feature is off), unknownComponent, salvageDisabled (the component itself is not salvageable), duplicate (the same actor, system, and component appeared twice in targets), or bulkLimit.
counts tallies every outcome above, plus total. posted is true only when at least one attempted (non-skipped) component’s crafting system has its Chat output feature on, regardless of whether that component’s own row succeeded. When none does, no aggregate chat card is posted at all, never an empty one. A subject that qualifies is folded into the ONE aggregated result card together with every other qualifying subject from the same run, never one card per component.
destroyComponents Outcomes
destroyComponents returns { items, unitsDeleted, documentsDeleted }. Each row of items carries { actorId, actorName, systemId, componentId, name, img, outcome, skipReason, requested, unitsDeleted, documentsDeleted, staleIds, items, vetoed }. outcome is succeeded (at least one unit was deleted), failed (units were found but none could be deleted), skipped (skipReason of unknownSystem, unknownComponent, or depleted), or notPermitted (the target named no resolvable actor).
Destroy removes the component’s WHOLE stack on the target actor, with no quantity control. It is deliberately not gated on the system’s Salvage feature or the component’s own salvage setup, since deleting an owned item is something a player could already do from the Foundry sheet. It posts no chat card, because a result card reports what an activity produced, and destroying produces nothing.
System-Owned Check Evidence
System-owned check results can also contain data.preRolls. Each entry records a separately evaluated modifier as { source, label, expression, total, destination } in evaluation order. The main total and diceGroups continue to describe only the authored check roll. Fabricate omits data.preRolls when no separately evaluated modifier completed, including cancelled, unrolled, and secret executions. Under the active roll-total-over-target evaluation, a dice-bearing Tool bonus joins the formula as a number and adds no entry. An entitled roll handoff carries serialized pre-rolls with its main serialized roll and reconstructs them for the recipient after GM execution, without rerolling. If that handoff cannot reconstruct its rolls, it refuses the chat post without rolling back the executed check. If Fabricate cannot serialize a dice-bearing Tool bonus’s roll, the check does not run, rather than applying a bonus whose roll was lost. A bundled post uses its chosen roll mode, or the posting client’s current default when no mode was chosen.
Actor Selection
These methods back the unified Fabricate window’s actor-selection bar and persist the remembered gathering actor:
Hooks.once('fabricate.ready', () => {
// Player-safe display data for the actor-selection bar.
const actors = game.fabricate.listSelectableActors();
// -> [{ id, uuid, name, img }, …]
const current = game.fabricate.getSelectedGatheringActorId(); // '' when unset
game.fabricate.setSelectedGatheringActorId(actors[0]?.id ?? '');
});
listSelectableActors()returns the current user’s selectable player characters (the GM-configured actor types that count as player characters, always including'character'), owned actors for players, all for GMs. Each record is redaction-safe display data containing only{ id, uuid, name, img }. No other actor internals are exposed. This selection list is narrower than gathering attempt authorization. An owned non-player-character actor stays attempt-authorized throughlistGatheringForActor/startGatheringAttemptbut does not appear in the bar.getSelectedGatheringActorId()reads the persisted remembered selection from thefabricate.lastGatheringActorclient setting, returning''when unset.setSelectedGatheringActorId(id)persists the remembered selection to that same client setting.
Hide Unavailable Environments Toggle
These methods back the player-side Hide unavailable toggle in the Gathering app’s Environments column. The toggle is a view-only presentation preference. It hides only listings the engine reports as locked === true (disabled environments, plus location-gated environments the party is not in). It never changes saved data, the engine listing, or GM configuration.
Hooks.once('fabricate.ready', async () => {
const hidden = game.fabricate.getHideUnavailableEnvironments(); // false by default
await game.fabricate.setHideUnavailableEnvironments(true);
});
getHideUnavailableEnvironments()reads thefabricate.gatheringHideUnavailableEnvironmentsclient setting, returningfalsewhen unset.setHideUnavailableEnvironments(value)persists the boolean preference to that same setting.
The setting is scope: 'client', so it persists in the browser’s localStorage. The choice is remembered per client/device, not per user account. The same account opening Fabricate on a second device or browser starts from the default (off).
Gathering Economy Block
getGatheringEconomy({ systemId }) returns the normalized per-system limitation block, and setGatheringEconomy({ systemId, economy }) (GM-only) persists it. The block carries two independent boolean flags. There is no single mode field:
Hooks.once('fabricate.ready', async () => {
const systemId = game.fabricate.listCraftingSystems()[0]?.id;
// Normalized shape — stamina and resource-node limitations toggle independently.
const economy = game.fabricate.getGatheringEconomy({ systemId });
// -> {
// stamina: { enabled: false, max: '', start: '', regen: { policy, unit, amount, lastRoll } },
// nodes: { enabled: false }
// }
// Anti-dogpiling: turn BOTH limits on. One accepted attempt then both depletes
// the node pool and spends stamina; neither flag on means no limit.
await game.fabricate.setGatheringEconomy({
systemId,
economy: { stamina: { enabled: true }, nodes: { enabled: true } }
});
});
The flags map onto the rich-state service accessors staminaEnabled(systemId) and nodesEnabled(systemId) (the single read used by enforcement, world-time regen/respawn drivers, and every UI surface). The derived economyMode(systemId) accessor is retained for back-compat and now returns 'both' | 'stamina' | 'nodes' | 'none' (the 'both' value is new in 0.8.0). Worlds upgraded from before 0.8.0 have their legacy economy.mode enum migrated into these flags automatically (see Gathering Limitations).
Realms, Parties, And Location
Location-aware gathering adds stores for world-level realms and parties, a current-realm resolver, and GM discovery controls. A Gathering Realm is the Fabricate geography concept (renamed from Gathering Region to avoid the collision with Foundry’s own Scene RegionDocument). A realm maps many-to-one onto Foundry Scene Regions through its scene mappings. Realms, their reveal mode and their modifier visibility are world data shared by every crafting system, and realm discovery is world-wide: a character who has found a place has found it, whichever system they were serving at the time. What is per crafting system is participation — the gatheringRealmSettings.enabled flag (default off, the Enable Travel & Realms toggle in that system’s Settings tab). Every method below still takes a systemId, which acts purely as that gate: while the flag is off, getGatheringLocationForActor, the override setters, and the discovery reveal/hide methods are inert (return null / false / no-op). Each method also has a shorter alias on the game.fabricate.gathering facade (getPartyStore, getRealmStore, getLocationService, getLocationForActor, setPartyRealmOverride, clearPartyRealmOverride, revealRealmForActor, hideRealmForActor). The pre-rename *Region* method and alias names are retained as deprecated delegates that warn once and forward, so existing macros keep working:
Hooks.once('fabricate.ready', async () => {
const systemId = game.fabricate.listCraftingSystems()[0]?.id;
const partyStore = game.fabricate.getGatheringPartyStore(); // party CRUD, members, travel actor
const realmStore = game.fabricate.getGatheringRealmStore(); // world realm CRUD + settings
const locations = game.fabricate.getGatheringLocationService(); // current-realm resolution
// GM-only writes.
await game.fabricate.setGatheringPartyRealmOverride({ partyId, systemId, realmIds: [realmId] });
await game.fabricate.clearGatheringPartyRealmOverride({ partyId, systemId });
await game.fabricate.revealGatheringRealmForActor({ actor, systemId, realmId });
await game.fabricate.hideGatheringRealmForActor({ actor, systemId, realmId });
// Player-callable, redaction-safe read: secret undiscovered realm ids/names
// are never disclosed to non-GM callers.
const summary = game.fabricate.getGatheringLocationForActor({ actor, systemId });
});
See Gathering Realms & Travel for the full feature guide, including the GM Travel route, environment location rules, and the disclosure policy.
Icon Vocabulary
Fabricate curates ONE icon vocabulary and draws every icon field in the module from it — essence icons, category icons, and the biome icons players see on gathering environment cards. listCuratedIcons() publishes that same vocabulary so a companion module can offer its GMs the icons Fabricate already offers, instead of hand-curating a second list that drifts from this one. findCuratedIcon(name) resolves one name against it, which is what you want when a GM has already saved an icon and you need to know whether it is still offered.
Hooks.once('fabricate.ready', () => {
const icons = game.fabricate.listCuratedIcons();
// -> [{ iconCode: 'abacus', label: 'Abacus', aliases: [] }, …]
// `iconCode` is bare, so a render composes the weight itself.
const [first] = icons;
const className = `fas fa-${first.iconCode}`;
// A GM's saved icon may use any of the glyph's names, so resolve rather than scan.
const saved = game.fabricate.findCuratedIcon('cog');
// -> { iconCode: 'gear', label: 'Gear', aliases: ['cog'] }
const stillOffered = saved !== null;
// Searching: the aliases are the other names a GM might type for the same picture.
const matches = icons.filter(({ iconCode, label, aliases }) =>
[iconCode, label, ...aliases].some((name) => name.toLowerCase().includes('cog'))
);
});
- There is one row per GLYPH, not one per name, and one weight. Several names routinely share one drawing, so the vocabulary offers one of them and records the rest as
aliases. Nothing is refused by that: every other name still resolves, throughfindCuratedIconor through thealiaseson the row. - Both methods build their records fresh on every call, down to the
aliasesarray, so you may keep, sort, filter or mutate what you are handed. Nothing you do to it reaches Fabricate’s own pickers. - The list is in the vocabulary’s own order, which is alphabetical by
iconCode. findCuratedIcon(name)answersnullfor a name the vocabulary does not offer — a typo, a name Foundry cannot draw, or a real icon the curation leaves out. It does not distinguish those cases, because a caller can do nothing different about them.- Both methods throw
Fabricate not initializedbefore Fabricate is ready, which is how this API refuses a premature call. Call them fromfabricate.ready, or wrap them and degrade to an empty result, as a composition edge should.
| Field | Type | Meaning |
|---|---|---|
iconCode | string | The bare name the vocabulary offers and you should persist, such as mortar-pestle. No fa- prefix and no weight. |
label | string | An English display name, not localized. On Foundry 14 it is Font Awesome’s own display name, such as Mortar Pestle. On every other generation it is derived from iconCode by capitalizing each hyphen-separated word, with a word of two letters or fewer in capitals, and it is Font Awesome’s display name again where the measurement came back empty. |
aliases | string[] | Every other name the same glyph answers to, such as ['cog'] on gear. Often empty. |
Do not validate a saved icon by scanning iconCode alone. icons.some(({ iconCode }) => iconCode === name) looks right and is wrong: a GM who saved fas fa-cog chose a glyph this vocabulary offers as gear, so that scan reports a perfectly good icon as unknown. Use findCuratedIcon(name), which resolves aliases and answers from the catalogue rather than from a guess.
What is not published, and why. The unfiltered catalogue stays internal, because no Fabricate picker renders it and publishing it would invite a companion to offer icons Fabricate’s own screens will not. It holds 1420 entries, narrowed from Foundry’s 3768 classic glyphs to the names Font Awesome also publishes for free, against the curated set’s 750. Fabricate’s internal exclusion predicate stays internal too: it answers whether a name matches an exclusion, not whether Foundry can draw it, so it reports a typo as unexcluded. That is the mistake findCuratedIcon exists not to make.
Generation awareness, provenance, and what still drifts. listCuratedIcons() and findCuratedIcon() answer with the same generation-aware vocabulary Fabricate’s own icon pickers offer on this client, not a set pinned to whichever Foundry release the catalogue was last generated against. On Foundry 14 that vocabulary is the committed catalogue described above, measured from the Font Awesome bundle Foundry 14.365.0 actually ships (Pro 7.2.0) rather than from Font Awesome’s published metadata, so a name in this list is a name a Foundry 14 client can render. On every other generation, including Foundry 13, Fabricate measures the running client’s own loaded Font Awesome stylesheet instead, so a name it offers is a name that client can actually render, and it falls back to the Foundry 14 catalogue only when that measurement comes back empty, such as before the stylesheet has finished loading. The Free-only filter applies either way, so a name a measured generation offers is still narrowed to Font Awesome’s free release. The committed catalogue itself is an artifact because CI has no Foundry install to read, and scripts/generate-icon-catalogue.mjs regenerates it from a given install, with --check reporting whether the bundle has moved without writing. What that does not do is re-check itself. Nothing runs the generator when Foundry bumps its bundled Font Awesome, so the committed snapshot ages: names added in a newer bundle are absent from the Foundry 14 vocabulary until someone regenerates it, and Font Awesome does retire and re-alias names between majors, which can turn an icon a GM chose into an alias of a different glyph. If you render a name from this list and get a blank glyph, that is the check to make.
Companion Contract
game.fabricate.api.companion is Fabricate’s named, versioned contract for outbound behavioural consumption — the capabilities a companion module needs to settle a downtime activity against an actor, or against a whole party. It is the behavioural sibling of the two navigation seams below, which are outbound UI contribution rather than consumption, and of the published UI components seam, by which a companion renders Fabricate’s own primitives into an element it owns.
The enumerable game.fabricate.api.COMPANION alias remains available for compatibility, but reading it warns once per client page session and points here for migration.
const contract = game.fabricate?.api?.companion;
if (!contract) return; // Fabricate has not loaded yet — retry, do not degrade.
if (contract.schemaVersion !== 1) return; // A version this companion does not understand.
The frozen descriptor retains the original schemaVersion, members, outcomes and callSites fields, with additive features for advertised capabilities. It is assigned when Fabricate’s own init listener runs, before any service exists. outcomes and callSites are both published so you can read a symbol rather than write a bare string; callSites matters most, because callSite is the one required input with no default, and invalidCallSite is the whole of a typo’s punishment.
Read the version in
setuporready, never in your owninit. Foundry dispatchesinitlisteners in module-script execution order, ordered by thelibrarymanifest flag and then world module-collection order;relationships.requiresdoes not influence that order, and Fabricate declares nolibraryflag. A companion sorting before Fabricate therefore readsundefinedat its owninit. Treat an absentgame.fabricateas Fabricate has not loaded yet — never as this Fabricate has no contract, and never as a trigger for a degraded path.
The Members
Every member is declared at exactly one promise tier, and nothing outside this set is contract however reachable it is.
| Member | Promise | Read from | What it answers |
|---|---|---|---|
schemaVersion | stable | the companion descriptor | The contract version, as a number. Readable before any service exists. |
grantRecipeKnowledge | stable | game.fabricate | ({ actorId, recipeId, grantedBy }) teaches one actor one recipe with no owned book required. GM-gated, idempotent, and it refuses where a learned entry would be invisible to the player. |
checkAffordability | stable | game.fabricate | ({ actorId, unitId, amount }) answers whether an actor can afford a cost against the world coin ladder. GM-gated, ladder-aware, single-unit, and this member writes nothing — creditCurrency below is the one that does. |
getCurrencyConfigStore | handle | game.fabricate | The world currency configuration store Fabricate itself uses, or null before readiness. Read it as getCurrencyConfigStore()?.get?.() ?? null, because .get() on the null throws. |
getActorPropertyCoinSpender | handle | game.fabricate | The coin spender for the actorProperty strategy, or null before readiness. |
getActorInventoryCoinSpender | handle | game.fabricate | The coin spender for the actorInventory strategy, or null before readiness. |
getCraftingEngine | handle | game.fabricate | The live crafting engine, or null before readiness. |
getCraftingEngine().findComponentItems | handle | the crafting engine | (actor, component, system) finds an actor’s existing stacks of a component, so an award can stack rather than duplicate. See its carve-outs below. |
rollActorCheck | stable | game.fabricate | ({ actorId, callSite, formula, dc, compare, label, interactive, rollDecision, evaluation }) rolls one Standalone Check Roll for one actor, graded against a dc or ungraded. It answers the total, dice groups, resolved formula and runner-produced evaluation metadata on a rolled outcome. GM-gated, call-site-gated, and a dismissed prompt is a refusal rather than a rolled failure. |
resolveBulkCheckDecision | stable | game.fabricate | ({ callSite, formulas }) settles one roll decision — situational bonus, roll mode, Advantage — for N rolls the caller will make. It rolls nothing, takes no actorId, and answers which of the caller’s formulas the decision covers. |
awardComponents | stable | game.fabricate | ({ actorId, callSite, systemId, awards }) places components on an actor’s sheet, stacking onto what they already hold rather than duplicating it. GM-gated, call-site-gated, not idempotent, and it answers one placements entry per requested award so partial success is legible. |
creditCurrency | stable | game.fabricate | ({ actorId, callSite, unitId, amount }) credits one denomination of the world coin ladder to an actor. GM-gated, call-site-gated, not idempotent, whole amounts only, and credited is null wherever Fabricate cannot prove what landed. |
readPooledHoldings | stable | game.fabricate | ({ actorUuids, costs }) answers what a set of characters holds between them — a component, a currency amount, a required tool — naming each cost by name and answering its pooled available, a derived sufficient and the ids that name resolved to. GM-gated, addressed by actor UUID, writes nothing, and it is exact at read time rather than a reservation. |
consumePooledHoldings | stable | game.fabricate | ({ actorUuids, callSite, costs }) takes costs from that same pool and answers a ledger naming which documents on which actors paid. GM-gated, call-site-gated, not idempotent, all-or-nothing, and a failure part-way through restores every component exactly — same _id, same flags, same effects — before refusing. |
What Each Promise Tier Guarantees
A stable member guarantees its name, its arguments, and its result shape. It never throws: it refuses in the same shape it succeeds in, carrying a stable outcome token beside a message that is always a localization key. Where a lower layer produces free text — a broken coin ladder, a macro’s own error — that text rides in messageData.detail so message stays localizable.
A handle member guarantees only the accessor’s name, and that it answers the object Fabricate itself uses or null before readiness. It guarantees nothing about that object’s method surface beyond a declared carve-out. CraftingEngine has hundreds of methods and no reviewer can promise them all, so the honest promise is the handle rather than the surface.
getCraftingEngine().findComponentItems is the one carve-out, and it is stated in full because a companion that guards only against a null actor still crashes. It takes documents, not ids. Its third argument is a crafting-system object, not an id. And it throws on a null actor and on a null component, with only the system argument tolerant.
Calling A stable Member
Every stable behavioural member that reads or acts on one specific actor takes an actorId, never an actor uuid, and resolves it through Fabricate’s own ownership gate. resolveBulkCheckDecision is the one that does not: it reads no actor, rolls nothing and writes nothing, so it takes none — an ownership gate on an argument a member never reads would advertise a check that is not there. The two pooled holdings members are the other exception, and they take an actorUuids list instead: they answer about a set rather than one actor, and the one of them that deletes needs an address an unlinked token cannot share with its prototype. That reasoning is in Reading And Taking Pooled Holdings below, and it is a stated departure rather than an inconsistency. Every stable behavioural member is GM-gated, and every one refuses rather than throws before the module is ready. The gate order is GM → actor → readiness, in that order, because the readiness check throws and must run after the refusals that may not. A member’s own request validation — including the callSite and election gates the two check-roll members add — runs after the readiness refusal. Two consequences follow, and they are stated here rather than left to be discovered: a GM holding a stale actorId answers noActor before any call-site check, and a pre-ready call answers notReady before invalidCallSite. That ordering is deliberate: under it a stale id answers noActor on every client, where an election-first order would report the same defect two different ways depending on which screen the GM was looking at. Uniformity beats the marginal precision.
const result = await game.fabricate.grantRecipeKnowledge({
actorId: actor.id,
recipeId,
grantedBy: 'Downtime: Research' // optional; refused, never truncated, max 64 characters
});
if (!result.success) return ui.notifications.warn(game.i18n.format(result.message, result.messageData ?? {}));
const alreadyKnew = result.outcome === game.fabricate.api.companion.outcomes.alreadyKnown;
An already-known recipe answers success: true with the alreadyKnown outcome and performs no write, because an automation tick may legitimately re-run. Branch on the outcome to tell granted now from already knew, never on the boolean.
checkAffordability answers { success, affordable, outcome, message }. success: false means the question could not be answered — an unknown unit, a non-positive amount, an empty or invalid ladder, an unreachable spender — and affordable is then null rather than a confident false. A shortfall is success: true with affordable: false, which is what keeps tell the player they are short apart from tell the GM their ladder is broken.
Rolling A Standalone Check Roll
rollActorCheck and resolveBulkCheckDecision publish Fabricate’s check-roll mechanics to a companion that owns no crafting system. The concept has a name, and the name has two axes that must not be collapsed.
“Standalone” is a claim about the crafting-system axis: the roll stands outside any CraftingSystem. It is not a claim about the game-system axis, where Fabricate is agnostic on every path including this one — a Standalone Check Roll is exactly as game-system agnostic as every other Fabricate check.
So this is not “a Fabricate check”. A Fabricate check is taken on a subject inside a crafting system and carries that system’s modifier catalogue, combination rule, tool bonuses, authored triggers, tier stepping and failure-result policy. A Standalone Check Roll is @-placeholder resolution against the actor’s roll data, the retired-placeholder shim, the Advantage/Disadvantage rewrite, the situational-bonus input with its formula-validity net, the roll mode and the chat post, and the pass/fail or raw-total answer — without the system-derived terms, because there is no system and no subject to derive them from. If you want a system’s modifiers applied, route a real craft or salvage instead.
This does not give a manual-fulfilment GM their physical-dice prompt back. Fabricate’s check path evaluates with
allowInteractive: falseunconditionally, and this member inherits that, so Foundry’s ownRollResolverstays suppressed. What the member opens is a different dialog: Fabricate’s own roll prompt, which confirms the roll, offers Advantage and a situational bonus, and — crucially — reports its own dismissal, so you can abort with zero mutation. Foundry’s dice resolver cannot do that: closing it fulfils the roll with a random face indistinguishable from a typed one.
const { callSites, outcomes } = game.fabricate.api.companion;
const result = await game.fabricate.rollActorCheck({
actorId: actor.id,
callSite: callSites.gmAction, // or callSites.broadcast; REQUIRED, and there is no default
formula: '1d20 + @prof',
dc: 15, // omit for an ungraded roll that just answers the total
compare: 'meet', // 'meet' (default) or 'exceed'
label: 'Downtime: Research', // optional; defaults to a localized activity noun
interactive: true // default false — no dialog, no chat post
});
if (result.outcome === outcomes.cancelled) return; // the GM dismissed the prompt: do nothing
if (!result.success) return ui.notifications.warn(game.i18n.format(result.message, result.messageData ?? {}));
if (result.passed) applyReward(result.total);
total is always the raw roll total, and it is null for every refusal — engineUnavailable and noFormula included. A legitimate rolled 0 answers 0, never null, so you can always tell a real zero from a refusal. passed is true, false, or null for an ungraded roll, which is not graded and therefore has no pass. diceGroups is a list, so its absence is [] rather than null.
evaluation is optional. When it is absent or undefined, Fabricate uses the shared Check Evaluation defaults. When supplied, it must be a plain data record with only recognized keys at every nested level. null is a supplied value and refuses evaluationInvalid. Unlike dc, label and rollDecision, it does not mean absent. A nested key whose value is undefined counts as omitted, so its default applies. Fabricate validates every supplied field before applying defaults, without coercing invalid types or replacing invalid values.
Read game.fabricate.api.companion.features.checkEvaluation before sending an evaluation. This additive features field leaves schemaVersion at 1. Its shape is { version, modes, additionalDice }: each modes row is { product, direction, targetSources, interactive }, and an evaluation is executable when one row matches its product and direction, lists its target.source in targetSources, and has interactive: true when the roll is interactive. version names this descriptor’s shape, not its rows. Activating a mode appends a row without changing it, so match rows rather than comparing versions. At version 1 the descriptor publishes five rows: { product: 'sum', direction: 'over', targetSources: ['fixed'], interactive: true }, { product: 'sum', direction: 'over', targetSources: ['attribute'], interactive: true }, { product: 'sum', direction: 'under', targetSources: ['fixed', 'attribute'], interactive: true }, { product: 'count', direction: 'over', targetSources: ['fixed', 'attribute'], interactive: true }, and { product: 'count', direction: 'under', targetSources: ['fixed', 'attribute'], interactive: true }. additionalDice is true, so a count evaluation whose pool has additional dice enabled may buy them through this member too, as described below. On the fixed sum-over row the evaluation only selects the mode, target.expression and the pool settings are validated but never change the roll, and Fabricate still grades formula against dc through compare, so a request without a finite dc rolls ungraded. On an attribute row Fabricate ignores dc entirely and resolves the target from target.expression against the actor’s roll data instead, using the same lookup Foundry’s own Roll.replaceFormulaData uses, plus the row’s baseAdjustment. An unresolved or non-numeric target refuses the outcome targetUnresolved before any roll, and an invalid multiplier refuses evaluationInvalid. A sum-under request against a fixed target with no finite dc also refuses evaluationInvalid rather than rolling ungraded. On a count row Fabricate ignores both formula and dc and grades the rolled dice pool’s net successes against evaluation.pool.required alone. An unresolved or non-numeric pool.base or pool.threshold refuses the outcome poolUnresolved before any roll, and any other invalid pool setting (die, explode, cancel, or the settled pool itself) refuses evaluationInvalid before Fabricate constructs a Roll. A pool that resolves to zero or fewer dice answers checkFailed with no Roll constructed at all. An interactive count request opens Fabricate’s roll prompt, which shows the dice pool and the successes needed rather than a formula or DC, and a situational bonus there adds dice or moves the threshold, as the pool’s modifierDestination says. A forwarded rollDecision applies its bonus the same way without opening the prompt. Advantage and Disadvantage move the pool by the default rule’s one die: an interactive count request that forwards advantage: 'advantage' adds a die, 'disadvantage' removes one, and the pool floor and zeroPoolFails apply after that adjustment. A count evaluation whose pool has additional dice enabled may buy them through a top-level additionalDice request key: a non-negative integer, honoured only on a non-interactive request and only from callSite: 'gmAction'. A non-zero additionalDice on a broadcast request refuses additionalDiceRefused with reason broadcastCallSite before any read, and a broadcast interactive request shows the prompt’s additional-dice control as unavailable for that same reason. A non-zero additionalDice on an interactive request refuses invalidRollDecision instead: there the player buys through Fabricate’s own roll prompt, or you forward a pre-resolved rollDecision.additionalDice, validated the same way and the only additional-dice key a forwarded decision carries. A non-zero additionalDice on any evaluation other than an enabled count refuses notOffered.
A refused purchase, or a refused spend, answers the outcome additionalDiceRefused: a success: false refusal with no executed fields, answered before any main roll. Its messageData is { label, reason, actor, resource, n, limit, available }, with reason one of the closed ADDITIONAL_DICE_REFUSALS list, and message is already that reason’s own sentence for the resource name you authored and the source you chose. An executed answer additionally carries boughtDice, the integer dice bought for that roll, 0 when none were bought. A main roll that still fails after a successful spend, for example once Foundry’s own dice-explosion limit is hit, answers evaluationInvalid with messageData.boughtDice, because the spend already stands and nothing is refunded.
A malformed evaluation returns evaluationInvalid. A valid evaluation whose mode is absent from the advertised rows returns evaluationUnsupported. Both outcomes are stable refusals before Fabricate prompts or rolls.
Only checkPassed, checkFailed and rolled results carry executed evaluation metadata from the runner: product, direction, comparison, target, margin, successes, cancelled and boughtDice (0 when none were bought). Every refusal omits those fields, including evaluation refusals, with one exception: a post-spend evaluationInvalid still carries boughtDice alone, because that spend already happened and stands. additionalDiceRefused is answered before any spend and carries no executed fields at all.
A graded answer against a resolved target, meaning an attribute row or any sum-under row, reports through FABRICATE.Check.Roll.PassedTarget or FailedTarget instead of the plain Passed/Failed keys, with messageData { label, total, target } taken from the roll’s own executed target, never from the request dc. Only the fixed sum-over row keeps Passed/Failed with { label, total, dc }. A graded count row reports through FABRICATE.Check.Roll.PassedCount/FailedCount instead, with messageData { label, total, required }, where total is the net successes the pool rolled. A zero pool reports through FailedCount’s sibling FailedZeroPool with messageData { label } alone, since neither a total nor a required count means anything with no dice rolled. An attribute target Fabricate could not read as a number answers the outcome targetUnresolved. Its message key is FABRICATE.Check.Roll.TargetUnresolved, whose English text is “{label} check could not read a number for its target from this character.” A count’s pool.base or pool.threshold Fabricate could not read as a number answers the outcome poolUnresolved. Its message key is FABRICATE.Check.Roll.PoolUnresolved, whose English text is “{label} check could not read a number for its dice pool from this character.”
callSite is required and has no default. Nothing in the request or the environment distinguishes your deliberate click from a synced updateWorldTime tick, so Fabricate refuses invalidCallSite rather than guessing. Declare broadcast from any handler that fires on every connected client, and Fabricate refuses notElected on every client but the elected GM’s. Declaring gmAction from a synced hook bypasses that gate entirely and puts the single-executor obligation back on you. The two accepted values are published as game.fabricate.api.companion.callSites, so read callSites.broadcast rather than retyping the literal: a mistyped string is refused as invalidCallSite and nothing else tells you it was a typo.
resolveBulkCheckDecision is for the case where you will roll for several characters at once and want to ask the GM once:
const { callSites, outcomes } = game.fabricate.api.companion;
const decision = await game.fabricate.resolveBulkCheckDecision({
callSite: callSites.gmAction,
formulas: characters.map((character) => character.downtimeFormula)
});
if (decision.outcome === outcomes.cancelled) return;
for (const index of decision.covered) {
await game.fabricate.rollActorCheck({
actorId: characters[index].id,
callSite: callSites.gmAction,
formula: characters[index].downtimeFormula,
dc: 15,
interactive: true,
rollDecision: decision.decision // requires interactive: true, or it is REFUSED
});
}
covered is the array of indices into your own formulas array, not the formulas themselves, because two characters may share a formula and you have to map the answer back onto your own subjects. A formula the retirement shim empties — @craftingmod, or anything built on it that cannot be rewritten — is not usable: it never appears in covered, it never denies Advantage to the rest of the batch, and rollActorCheck refuses it as noFormula rather than silently passing a graded check with the DC ignored. A batch in which nothing can roll answers nothingToDecide with success: true and opens no dialog.
A rollDecision supplied with interactive: false is refused as invalidRollDecision, not silently discarded: the evaluator only consults one on its interactive path, so your bonus, Advantage and roll mode would otherwise all vanish with no error while the base formula rolled.
There is no separate rollMode argument to rollActorCheck: the roll uses the client’s own default unless the rollDecision you forward carries one, and decision.decision.rollMode (when present) overrides that default the same way bonus and advantage do. Its accepted values are publicroll, gmroll, blindroll, and selfroll, and resolveBulkCheckDecision’s own picker never hands you anything outside that list, so forwarding its answer unmodified cannot produce an invalid one.
Placing A Reward
awardComponents and creditCurrency are the two members that write value onto a character. Everything in this section follows from that, and none of it applies to the members above.
const { callSites, outcomes } = game.fabricate.api.companion;
const award = await game.fabricate.awardComponents({
actorId: actor.id,
callSite: callSites.gmAction, // REQUIRED, exactly as on the check-roll members
systemId, // one crafting system per call, never per entry
awards: [{ componentId, quantity: 3 }] // at most 64 entries; the keys are exactly these two
});
for (const placement of award.placements) { // one entry per requested award, in YOUR order
if (placement.outcome !== outcomes.awarded) log(placement.componentId, placement.message);
}
const credit = await game.fabricate.creditCurrency({
actorId: actor.id,
callSite: callSites.gmAction,
unitId: 'gp',
amount: 50 // a positive whole number, or a string naming one
});
Neither member is idempotent, and you own not double-awarding. Awarding 3 hides twice is legitimately 6 hides, and crediting 50 gp twice is legitimately 100 gp, so there is no state Fabricate can read that tells a duplicate award from a second intended one. grantRecipeKnowledge is idempotent only because the learned map is its own key, and nothing equivalent exists here. Fabricate will not add an award id it dedupes on: a per-actor ledger of caller-supplied ids is a persisted shape with unbounded growth and no restore semantics, and a partial guarantee is more dangerous than a published non-guarantee. Record your claim in front of the irreversible act rather than guarding inside it — write “this activity has been settled” first, then award.
Retry only the outcomes Fabricate declares to have mutated nothing. success is not the axis, and neither is a zero amount.
| Member | Safe to retry |
|---|---|
awardComponents | gmOnly, noActor, notReady, invalidCallSite, notElected, invalidAwards, systemNotFound, awardFailed |
creditCurrency | gmOnly, noActor, notReady, invalidCallSite, notElected, invalidAmount, ladderEmpty, ladderInvalid, unitNotFound, creditNotConfigured |
Anything else may have moved value, and retrying it double-awards. That includes partiallyAwarded, and it includes creditFailed — which is the trap, because the obvious “retry on success: false” policy then double-credits exactly when a GM’s currency macro is broken and the GM cannot see it happening. awardFailed is inside its set because that member runs no code Fabricate does not own, so every one of its failures is an observed non-write; creditFailed is outside it because under two of the three currency spend strategies the mechanism is a GM’s macro or a game system’s own adapter.
Both members address WORLD actors, so an unlinked token cannot be awarded. An unlinked token’s synthetic actor carries its base actor’s id, so passing that id addresses the world prototype: you get success: true, and the items or coin land on a sheet the player never opens. This is not a lookup Fabricate declines to make — every unlinked token created from one base actor shares that id, so an actorId could not tell two of them apart even in principle. The remedies are: link the token, or do not use these members for it. Foundry’s own handle for a synthetic actor is fromUuid("Scene.<id>.Token.<id>.Actor.<baseActorId>"); Fabricate’s actor-targeted members take an actorId by convention, and that convention is what this limit is.
awardComponents answers per entry, and awarded is a total it computed itself. placements holds one { index, componentId, requested, placed, stacked, outcome, message } per requested award, in your order and with placements[i].index === i, so you can map the answer back onto your own array without having kept it. It is [] for a refusal taken before anything was attempted, and fully populated when everything was attempted and nothing landed — that pair is how you tell those two apart. awarded is the sum of placements[].placed, it is null for a pre-attempt refusal, and it is 0 for awardFailed. stacked tells “added 3 to an existing stack” from “created a new item”, which is the fact findComponentItems was published to let you record. A failing entry does not stop the entries after it: an award is a give, so the loop accumulates rather than aborting.
A multiUnitUnsupported entry has two possible causes, and only one of them is a limit. Fabricate writes your quantity into the item payload and then reads back what it wrote, and when the stored value is not the requested one it refuses a multi-unit request rather than creating a single item and reporting N. If the game system’s item schema genuinely carries no quantity field, that is a real capability limit and single-unit awards are the honest workaround. If instead the GM’s configured stack-quantity path is wrong, do not loop single awards: that leaves N loose documents that will never stack, which is the duplicate-versus-stack failure these members exist to prevent. Point the GM at Fabricate’s own stack-quantity path advisory, which diagnoses exactly that misconfiguration.
credited is three-valued, and 0 never means “the credit failed”. It is the amount for credited. 0 for creditNotConfigured and for every refusal taken before any mechanism ran. And null for both creditFailed and creditUnavailable. So 0 means Fabricate can prove nothing moved and null means Fabricate cannot say, exactly as affordable: null already works on checkAffordability, with outcome carrying the rest. awardComponents’ awarded is null rather than 0 for that same refusal class, and the two are consistent rather than in disagreement: awarded is a sum over placements[], so an empty attempt record makes the sum vacuous rather than zero, while credited has no companion structure to be vacuous over.
In a
macrocurrency world, a credit runs the GM’sincrementmacro. That macro has until now run only on a player-cancelled craft, so a credit hands itrecipe: nullandcraftingSystem: null, and anincrementmacro that readscontext.recipe.namewithout checking throws on every credit. Tell the GM to branch oncontext.caller: the pair(macro key, caller)now separates eight occasions, not four —canAffordwith"craft"is the craft-time gate,canAffordwith"award"ischeckAffordability,decrementwith"craft"is the craft-time spend,decrementwith"consume"is the pooled holdings debit (see Reading And Taking Pooled Holdings below),balancewith"consume"is the pooled holdings read (below),incrementwith"craft"is the cancel refund,incrementwith"consume"is the pooled debit’s own intra-call give-back (below), andincrementwith"award"iscreditCurrency. That last cell is not unique: a pooled consume that has to unwind a currency cost it already settled gives it back THROUGHcreditCurrency’s own mechanism, so a GM’sincrementmacro sees"award"for that unwind exactly as it does for a credit a companion asked for outright, and it does not need to tell the two apart — both are Fabricate returning coin it is entitled to return. A world with noincrementmacro configured is a normal state rather than a broken one, and answerscreditNotConfigured— the GM’s to fix, and never reported as the spender declining.balanceis optional in the same way; amacroworld with neitherincrementnorbalanceauthored keeps every craft-time behaviour unchanged and simply cannot refund a cancel or answer a pooled read.
Reading And Taking Pooled Holdings
readPooledHoldings and consumePooledHoldings answer about a set of characters rather than one. A downtime stage’s requirements name a component, a required tool and an amount of coin, and the question a companion actually has is whether the party can cover them between them — then, if it can, to take them. Every read Fabricate published before this pair was single-actor and single-axis, so a companion could only compose that answer by summing several of them, and a sum a caller composes is a sum Fabricate can promise nothing about.
Both members address their actors by UUID, and that is a departure with a reason. Every other actor-targeted member takes an actorId, and that convention cannot address an unlinked token: the synthetic actor’s id is its base actor’s id, so a token-scoped id silently resolves to the world prototype. For a member that gives, the consequence is that value lands on a sheet the player never opens — bad, but recoverable. For a member that deletes, the same ambiguity would destroy items on the prototype every other token is derived from while the token that should have paid keeps its own. So the pair takes actorUuids, and fromUuid("Scene.<id>.Token.<id>.Actor.<baseActorId>") addresses the token’s own actor exactly.
Names or ids go in on the read; only ids go in on the consume. The read takes human-written names on all three axes — "Iron Ingot", "gp", "Smith's Tools" — and answers the canonical systemId, componentId and unitId those names resolved to. It takes those ids too, in the same name field: an exact id wins outright and anything else falls through to the folded name tier, on every axis. So a companion that reads once, caches what came back and later refreshes it can hand the ids straight back rather than returning to the authored name it already replaced — and a rename between the two calls cannot redirect it. The consume takes those resolved ids and refuses to guess from a name, because Fabricate’s owned-item name matcher is case-sensitive and deprecated and no stable promise that authorises a delete is going to be built on top of it.
A name Fabricate printed is a name Fabricate accepts. A coin resolves by its id, its abbreviation or its label. An exact id match wins outright, so a caller that already holds Fabricate’s internal unit ids behaves exactly as it did; otherwise every name folds into one case-insensitive tier in which abbreviation and label rank level. Ranking them would settle a genuine collision by a coin flip that looks authoritative, and currencyUnitDisplayName renders whichever of the two is present — so a caller holding a string Fabricate printed cannot know which field it came from.
ambiguous is reported and never resolved silently, on every axis. A component name that matches in two crafting systems, or a coin name that answers to two units, sets ambiguous: true on that reading and resolves to the first in order. You are about to consume by the id the read handed back, so a quietly chosen system is a quietly chosen set of documents and a quietly chosen coin is a quietly chosen debit.
const { callSites, outcomes } = game.fabricate.api.companion;
const actorUuids = party.map((character) => character.uuid); // at most 32
const read = await game.fabricate.readPooledHoldings({
actorUuids,
costs: [ // at most 32; the keys are EXACTLY these three
{ type: 'component', name: 'Iron Ingot', quantity: 4 },
{ type: 'currency', name: 'gp', quantity: 2 },
{ type: 'tool', name: "Smith's Tools", quantity: 1 }
]
});
if (!read.success) return ui.notifications.warn(game.i18n.format(read.message, read.messageData ?? {}));
if (read.readings.some((reading) => reading.ambiguous)) return askTheGmWhichOneTheyMeant(read.readings);
if (read.readings.some((reading) => reading.sufficient !== true)) return reportShortfall(read.readings);
const take = await game.fabricate.consumePooledHoldings({
actorUuids,
callSite: callSites.gmAction, // REQUIRED, exactly as on the award members
costs: [ // resolved IDS, from the read above
{ type: 'component', systemId: read.readings[0].systemId,
componentId: read.readings[0].componentId, quantity: 4 },
{ type: 'currency', unitId: read.readings[1].unitId, amount: 2 }
]
});
if (take.outcome !== outcomes.consumed) return reportRefusal(take);
The read’s cost key set is closed to exactly { type, name, quantity }. An entry carrying a fourth key — a systemId you already know, say — refuses the whole call as invalidCosts rather than that one cost. A tool cost carries a quantity it cannot spend, because one uniform entry shape is what lets you build a stage’s cost list without branching on the axis.
The consume names its number quantity on a component cost and amount on a currency cost. That is the shipped spelling on each axis — awardComponents takes a quantity and creditCurrency takes an amount — and the pooled consume follows both rather than inventing a third. The read has no such split because it asks the same question of all three axes.
The read is exact at read time and is NOT a reservation. Nothing stops an item being sold, dropped or consumed between the two calls, and nothing here takes a lease. A caller that must not overdraw calls the consume and reads its refusal, rather than treating a sufficient it read a moment ago as a promise.
null means Fabricate cannot see, and 0 means it can prove there is none. A component nobody in the party is carrying reads a confident available: 0. A currency cost in a world whose coin ladder is empty or invalid — or a macro world that has published no balance macro, or a party with one actor whose purse could not be read — reads available: null with the reading’s own balanceNotConfigured outcome. sufficient is null wherever available is, so the pool is short and the pool could not be read never collapse into the same confident false. balanceNotConfigured is a reading-level outcome and blocks nothing: the other costs in the same request are still answered.
A tool reading is the one exception to all of that. It answers a state of present, damaged or missing and no available at all, and its sufficient is state === 'present' and nothing else. A damaged tool is physically there and still answers false, because Fabricate’s own start-attempt tool gate refuses one and a gate built on the state token alone would admit it.
What The Consume Guarantees
Components are taken first and coin last, and the order is not arbitrary. A deleted component has an exact inverse: Fabricate snapshots item.toObject() before the delete and re-creates with { keepId: true, keepEmbeddedIds: true }, so the _id — and therefore the UUID — survives, active effects keep their own ids, and flags and system data return verbatim. Currency is the leg whose inverse may be absent or lossy: under macro the increment macro is explicitly optional, under pf2e a give-back creates treasure Items, and under actorProperty it lands in the unit’s own denomination rather than the base unit that was debited. So the recoverable leg goes first, and a currency cost is refused up front — creditNotConfigured, having written nothing — in a world that has published no way to give coin back at all.
Three costs of that restore are accepted rather than hidden. A restore fires createItem per document, because noHook gates only the pre-hook, so Fabricate’s own fragment-discovery and recipe-learning hooks can chatter on an undo. The restored document is also a new JS object, so a third-party module holding an Item reference across the take holds a stale one even though the UUID still resolves. _stats.modifiedTime and lastModifiedBy are refreshed, but createdTime is not preserved: Foundry tags a creation’s own createdTime with that write’s own timestamp regardless of what the payload supplies, and a keepId restore is a creation, so the restored item reads as freshly created rather than carrying its original age. And on an unlinked token actor, the restore promotes an inherited item to a delta-managed one: an unmodified item on the token was inherited from the base actor before the take, the delete writes a tombstone, and the keepId re-create lands as a managed record on the token’s own delta instead. The uuid, _id, effect ids, flags and system data are all identical, so nothing your integration can observe changes — but the item no longer tracks later edits to the base actor, and only core’s own EmbeddedCollectionDelta#restoreDocuments re-links it, which is not a route this API exposes.
A shortfall anywhere refuses everywhere. One cost the pool cannot cover refuses the whole call as insufficient before anything is written, with every ledger row reporting attempted: false. A partly-paid downtime cost is worse than an unpaid one.
The ledger is the machine-readable truth, and Consume.Failed does not promise more than it can keep. ledger holds one row per cost in your order with ledger[i].index === i, and each row’s takes name which document on which actor paid how much. consumed is summed from the rows, which are summed from their own takes, so no two published figures can disagree. Read it as a four-way discrimination, because success alone cannot carry it:
A take’s quantity is not in the unit you asked in, and two fields on the take say so. A currency cost is settled per payer in the world’s terminal base unit, because expressing each payer’s slice in a higher denomination would over-charge the pool by up to baseValue - 1 per payer. So a row echoing requested: 250 in gold sits beside takes counted in copper, and printing one next to the other prints nonsense.
take.unitIdnames the unittake.quantityis counted in —nullon a component take, which is a count of things and has no unit.take.shareis that same figure decomposed down your world’s own ladder into whole coins:15003base units reads[{unitId: 'gp', unitLabel: 'gp', amount: 150}, {unitId: 'cp', unitLabel: 'cp', amount: 3}].[]on a component take.
Both arms answer both fields, so you can draw a take without first asking what kind of cost produced it. Use share for anything a person reads and quantity for anything you do arithmetic on; they are the same number, and the decomposition sums back to it exactly.
| What the answer says | What actually happened |
|---|---|
consumed === null, ledger is [] | The request itself was refused before any cost was priced. Nothing was written. |
consumed === 0 and every row attempted: false | The pool was priced and the call refused. Nothing was written. |
consumed === 0 and some row attempted: true | Writes were issued and every one of them was given back. |
consumed > 0 beside consumeFailed | Writes were issued and the give-back did not fully complete. That much is still gone, and the takes name from whom. |
The last row is the one to defend against, and it is why the failure message says a give-back was attempted rather than that everything was put back. A row whose whole component bucket failed before the give-back reports its full planned allocation rather than the part that was written, which over-states on the safe side: a GM deciding whether to make a player whole again is better served by a number that cannot be too small.
Retry only when the answer says nothing was written. That is the first two rows of the table above, and success is not the axis. By outcome, the zero-mutation set is gmOnly, noActor, notReady, invalidCallSite, notElected, invalidActorUuids, invalidCosts, insufficient and creditNotConfigured. consumeFailed is not in it — some consumeFailed answers wrote nothing and some did not, and only the ledger says which.
The consume is not idempotent, and you own not double-consuming. Taking three hides twice is legitimately six hides gone, and nothing readable distinguishes a duplicated call from a second, intended one — exactly awardComponents’ position, for exactly its reason. The callSite election removes the steady-state multi-client duplication class; it is not a lease. Record your claim in front of the irreversible act rather than guarding inside it.
Both members fail closed on an actor set that does not fully resolve, and the two refusals split on what resolved. noActor means not one of the supplied UUIDs addressed an actor — the same word every other actor-targeted member answers. invalidActorUuids covers the request itself: an absent, empty or over-bound list, a non-string entry, or a list where some resolved and some did not. It also covers a list naming the same actor twice, which is easier to do than it sounds: a linked token’s actor is its base actor, so Actor.x and Scene.s.Token.t.Actor.x are two addresses for one document. Build the set from a party plus the acting character and you can send that pair without noticing. Distinctness is judged by document identity rather than by id, because an unlinked token’s actor shares its base actor’s id and is a genuinely different pool.
An address inside a compendium is refused, not read: a compendium actor is a template, and neither member will read from or take from one. Silently dropping one would compute a pool over fewer actors than you believe, and the consume would then draw from a different set than the read reported, so the resolved set is echoed back on actorUuids for you to check.
Both lists are bounded at 32. Not 64, as awardComponents’ awards is, because the work here is the product of the two: every cost is scanned across every actor, and the consume then issues one batched write per actor that paid. Widening a published bound is free under the compatibility promise and narrowing one is a schemaVersion bump, so the cheap direction is the one left available.
A currency row’s
requestedandconsumedare in different denominations, and that is deliberate.requestedechoes your own unit faithfully, because the contract promises you can map an answer back onto the request you wrote. The takes are in the ladder’s terminal base unit, because that is the only denomination in which a debit split across several payers is exact. So on agp → sp → cpladder a 2 gp cost readsrequested: 2besideconsumed: 200. Converting the takes back was rejected because a payer’s share becomes fractional — a three-way split of one gold piece does not sum back to one in floating point — and collapsing them into a single whole-cost take was rejected because it discards the per-actor attribution the ledger exists to provide. The read does not have this seam: itsavailableis converted back into your own unit and floored, because a pool holding three and a half gold pieces cannot pay four.
An unreadable pool refuses the consume at CALL level, and no row explains why.
balanceNotConfigured,ladderEmptyandladderInvalidare declared by the read and have no token in the consume’s key table. A read can report one unreadable cost and answer every other; a take that cannot see what a party is carrying must not take from them at all. So a consume in that world answersconsumeFailedat call level with every row reportingnotAttempted, and nothing written. If you need to know why, call the read: it answersbalanceNotConfiguredon the currency reading itself and names the cause in its own message.
A consume can emit issue-540 name-tier telemetry, and so can the read. Both resolve an actor’s owned stacks through the published findComponentItems, which falls back to a case-sensitive exact-name match whenever no owned item resolved to the component by durable identity, and reports every such hit through deprecation telemetry. That is correct here — this pair must match exactly what salvage and bulk destroy match, or a gate would predict a write it does not perform. What the read avoids is the other hop: resolving your cost’s name to a crafting-system definition goes through the definition index’s own silent primitive, so a companion polling holdings every stage does not register as reliance on the name fallback. The item-side hits are deduped per session on (systemId, definition, item name), so polling cannot inflate them either.
The Outcome Vocabulary
companion.outcomes is open by declaration and closed by enumeration: it is complete for this schemaVersion, a member may emit a new outcome without a version bump, and renaming or removing one is a bump. Branch on success first and treat an unrecognised outcome as a generic refusal — an exhaustive switch is a caller bug, not a contract breach.
The Compatibility Promise
While schemaVersion is unchanged, every member keeps its name, keeps accepting the arguments documented here, and keeps answering in the documented shape. A member may gain an optional argument or an additional result field; it may not lose one, change the meaning of one, or begin throwing where it returned a result. A new member may be added without a version change, because adding one cannot break a companion that does not call it. Removing a member, renaming one, or narrowing what one accepts is a schemaVersion bump, announced in the release notes, with the previous member retained as a deprecated delegate for at least one minor release. Nothing outside the declared set is contract, however reachable it is.
Elect a single executor before acting on an answer. A companion invoking any member from a handler that fires on every connected client — a synced hook such as
updateWorldTime, or a socket broadcast — must checkgame.users.activeGM?.id === game.user?.idfirst. Reading is harmless; acting on the read from N clients is not, andgrantRecipeKnowledgeunder N clients is N writes.For the five members that take a
callSite—rollActorCheck,resolveBulkCheckDecision,awardComponents,creditCurrencyandconsumePooledHoldings— Fabricate discharges this for you, but only if you tell it the truth. DeclarecallSite: 'broadcast'and Fabricate refusesnotElectedon every unelected client. DeclarecallSite: 'gmAction'from a synced hook and the gate never runs, because the declaration is the only signal Fabricate has and nothing in the environment can check it. The harm the two check-roll members guard against is sharper than a duplicated message: N clients roll N different totals and hand them to N copies of your module. For the two award members the harm inverts and gets worse: N clients place N copies of the same value onto a player’s sheet, with noalreadyKnownno-op to absorb the repeat and nothing for a GM to do but find and reverse it by hand. ForconsumePooledHoldingsit is worse again, because N clients delete N times the components and take N times the coin, across a whole party at once.
Subscribing To Gathering Hooks
Fabricate publishes Foundry hooks when a gathering attempt resolves, so other modules can react to gathering outcomes (successes, failures, and triggered encounters) without depending on Fabricate internals. Publication is always on — no setting gates it, and it is harmless when nobody subscribes. The hook names are also exposed on game.fabricate.api.HOOKS.gathering so you do not have to hard-code the strings.
| Hook | Fires |
|---|---|
fabricate.gathering.attemptCompleted | Once for every terminal attempt (success or failure, immediate or matured timed run), after all side effects are committed. |
fabricate.gathering.eventTriggered | Once per encounter/event the attempt triggered. |
The attemptCompleted payload is a cloned, JSON-serializable object:
| Field | Description |
|---|---|
schemaVersion | Payload contract version (currently 1). |
status | 'succeeded' or 'failed'. |
initiatedBy | 'immediate' for direct attempts, 'timed' for matured timed runs. |
worldTime | Foundry world time at completion. |
userId, viewerId | Initiating user and viewing user ids. |
actorId, actorUuid, actorName | The gathering actor. |
craftingSystemId, craftingSystemName | The owning crafting system. |
environmentId, environmentName | The gathering environment. |
taskId, taskName | The resolved task. |
runId, runStatus | The persisted gathering run. |
riskLevel, conditions | Risk and the weather/time-of-day snapshot (null for non-rich tasks). |
gatheredItems | [{ actorUuid, itemUuid, componentId, quantity }] created on success. componentId is null when the resolution does not expose it. |
usedTools | [{ componentId, actorUuid, itemUuid, quantity, broken }] consumed by the attempt (breakage internals are not exposed). |
events | The triggered encounters (also emitted individually as eventTriggered). |
checkResult | The normalized resolution detail. |
Where it fires. The hook fires on the client that resolved the attempt. Immediate attempts fire on the acting user’s client; matured timed runs fire once, on the primary GM client (so the updateWorldTime broadcast does not duplicate them across clients).
For a blind task viewed by a non-GM, the payload is redacted to match what that client may see: taskId/taskName, gatheredItems, usedTools, events, and checkResult are omitted, and no eventTriggered hook fires. A subscriber that throws is caught and logged — it never breaks the gathering flow.
Hooks.once('fabricate.ready', () => {
const { ATTEMPT_COMPLETED, EVENT_TRIGGERED } = game.fabricate.api.HOOKS.gathering;
Hooks.on(ATTEMPT_COMPLETED, (result) => {
if (result.status !== 'succeeded') return;
console.log(`${result.actorName} gathered`, result.gatheredItems, `in ${result.environmentName}`);
});
Hooks.on(EVENT_TRIGGERED, ({ actorUuid, event }) => {
console.log(`Encounter for ${actorUuid}:`, event.name);
});
});
Manager Navigation Extension
Companion modules can take over a Fabricate GM Manager navigation surface through the API-v1 manager extension seam. Today Fabricate renders one such surface, downtime, whose default content is Core’s read-only preview. A registered provider replaces that preview’s tabs, panel content, route chrome, and header actions.
The
downtimesurface may not be present. While the premium Downtime Studio is unreleased, Fabricate’sWorld > Downtimeroute is gated behind the world settingfabricate.experimentalFeatures, which is off by default. Registration is unaffected and never fails because of it — but with the setting off your provider is never mounted, so if your panel does not appear, check that setting before you debug your module. See When the surface is absent.
Declare Fabricate as a required module dependency in the companion manifest. Attempt registration once from the companion’s init callback. If the API is unavailable there, arm one existing Foundry ready fallback. Do not patch the Manager DOM or use Foundry render hooks.
{
"relationships": {
"requires": [{ "id": "fabricate", "type": "module" }]
}
}
relationships.requires governs dependency availability and activation. It does not establish ordinary-module script priority. The one-shot ready fallback is therefore part of the load contract. Do not replace it with an order assumption or a render-hook or DOM-patching integration.
Arm that fallback from inside your init callback, exactly as the example below does, and never at your module’s ESM top level. The placement is load-bearing for the same script-ordering reason on both seams, and Player Navigation Extension sets that reason out in full.
Worked Example
let unregisterDowntime = null;
let readyFallbackArmed = false;
// The provider declares its OWN tabs. These ids are the companion's, not Fabricate's:
// any non-empty ids, at least one of them, rendered in this array's order.
const TABS = [
{ id: 'board', icon: 'fas fa-chart-simple', key: 'Board' },
{ id: 'projects', icon: 'fas fa-hammer', key: 'Projects' },
{ id: 'factions', icon: 'fas fa-flag', key: 'Factions' },
{ id: 'rumours', icon: 'fas fa-comments', key: 'Rumours' },
{ id: 'rules', icon: 'fas fa-sliders', key: 'Rules' },
];
function tryRegisterDowntime() {
if (unregisterDowntime) return true;
const register = game.fabricate?.api?.managerExtensions?.registerWorldNavProvider;
if (typeof register !== 'function') return false;
unregisterDowntime = register({
apiVersion: 1,
id: 'downtime',
// A default header action for any tab that declares none of its own.
actions: [
{ id: 'guide', label: game.i18n.localize('MY_MODULE.Guide'), icon: 'fas fa-book',
href: 'https://example.com/downtime-guide' }
],
tabs: TABS.map(({ id, icon, key }) => ({
id,
icon,
// Required, and already localized by the companion.
label: game.i18n.localize(`MY_MODULE.Downtime.${key}.Label`),
accessibleName: game.i18n.localize(`MY_MODULE.Downtime.${key}.Accessible`),
tooltip: game.i18n.localize(`MY_MODULE.Downtime.${key}.Tooltip`),
// Optional route chrome. Fabricate keeps its own string for anything omitted.
title: game.i18n.localize(`MY_MODULE.Downtime.${key}.Title`),
subtitle: game.i18n.localize(`MY_MODULE.Downtime.${key}.Subtitle`),
breadcrumb: game.i18n.localize(`MY_MODULE.Downtime.${key}.Crumb`),
actionsLabel: game.i18n.localize(`MY_MODULE.Downtime.${key}.Actions`),
// Optional per-tab header actions, overriding the provider-level list above.
actions: id === 'projects'
? [{
id: 'new-project',
label: game.i18n.localize('MY_MODULE.NewProject'),
icon: 'fas fa-plus',
primary: true,
disabled: !game.user.isGM,
onSelect: (context) => openProjectDialog(context.craftingSystemId)
}]
: undefined,
})),
mount({ target, tabId, context }) {
const view = mountCompanionDowntime({ target, tabId, context });
// Re-render this surface whenever the companion's own data changes.
const stop = myDowntimeStore.subscribe(() => context.requestRemount());
return () => { stop(); view.destroy(); };
},
});
return true;
}
Hooks.once('init', () => {
if (tryRegisterDowntime() || readyFallbackArmed) return;
readyFallbackArmed = true;
Hooks.once('ready', tryRegisterDowntime);
});
Provider Contract
registerWorldNavProvider(provider) returns an idempotent unregister function. Call it when disabling the companion; doing so restores Fabricate’s own preview for that surface.
| Field | Required | Meaning |
|---|---|---|
apiVersion | yes | Must be exactly 1. |
id | yes | The surface id this provider claims. Any non-empty string; Fabricate’s Manager renders downtime. One provider per surface id — registering a second for the same surface throws. |
tabs | yes | One or more tabs, rendered in array order. |
actions | no | Default header actions for any tab that declares none of its own. |
mount | yes | Synchronous mount callback. |
Each entry in tabs:
| Field | Required | Meaning |
|---|---|---|
id | yes | Non-empty, unique within the tab set. Fabricate never checks it against a list of its own. |
label | yes | Localized visible tab label. It is the rail sub-item’s visible text, and the accessible name of the panel region below it. |
accessibleName | yes | Localized accessible name of the rail sub-item, and of Fabricate’s own preview tab button. It REPLACES the visible label as that control’s accessible name, so it must contain the label’s text. |
tooltip | yes | Localized tab tooltip. Over your screens it is the rail sub-item’s native tooltip, so it is pointer-visible rather than keyboard-visible; on Fabricate’s own preview strip it is a keyboard-visible role="tooltip". |
icon | yes | Font Awesome class string. |
title | no | Localized page title (the H1) while this tab is active. |
subtitle | no | Localized page subtitle while this tab is active. |
breadcrumb | no | Localized leaf breadcrumb crumb while this tab is active. |
actionsLabel | no | Localized accessible name of the header-action group. |
actions | no | Header actions for this tab, replacing the provider-level list. |
badge | no | { count, accessibleName } rendered on the tab’s rail sub-item. See Tab Badges. |
A tab’s key set is closed. Fabricate refuses a key it does not name above, with a deterministic message, exactly as Runtime Route Chrome refuses an unknown key. This is stricter than earlier releases, which silently ignored an unrecognized tab field.
Each action is { id, label, icon?, tooltip?, primary?, tone?, disabled? } plus exactly one of:
href— an absolutehttp(s)URL. Fabricate renders an anchor withtarget="_blank"andrel="noopener noreferrer". Any other scheme is rejected at registration.onSelect(context)— a click handler. Fabricate renders a button and calls the handler with the mount context plusactionId. A throwing handler is caught and logged.
All strings a provider supplies are used verbatim: localize them yourself. Fabricate localizes only its own fallback copy.
tone selects the action’s button treatment: primary, ghost, danger, or neutral, the default, which is the plain Manager button with no added styling. Every header action renders at the page header’s 38px control height and carries fabricate-button is-size-38, so a companion’s actions match Core’s own. primary: true is the older, still-supported spelling of tone: 'primary'. An action that declares both primary and tone is refused at registration.
Tab Badges
A tab may declare a badge — a small mark on its rail sub-item saying something is waiting there, e.g. “3 claims to review”:
tabs: TABS.map(({ id, icon, key }) => ({
id,
icon,
label: game.i18n.localize(`MY_MODULE.Downtime.${key}.Label`),
accessibleName: game.i18n.localize(`MY_MODULE.Downtime.${key}.Accessible`),
tooltip: game.i18n.localize(`MY_MODULE.Downtime.${key}.Tooltip`),
badge: pendingCountFor(id) > 0
? { count: pendingCountFor(id), accessibleName: `${pendingCountFor(id)} pending` }
: undefined,
})),
badge is { count, accessibleName }. Both fields are required whenever badge is present, and no other key is accepted. count is a non-negative integer; count: 0 renders the numeral 0 rather than nothing, so a companion that wants to state “nothing pending” explicitly can. accessibleName is final display text, rendered verbatim, exactly as a tab’s own label is: localize it yourself, and never pass a lang key expecting Fabricate to resolve it.
Change a badge at runtime, with no mount and no remount, through the registry itself:
game.fabricate.api.managerExtensions.setWorldNavTabBadge('downtime', 'board', {
count: 3,
accessibleName: '3 claims to review',
});
// Clear the runtime layer and fall back to the tab's own registered badge (or none).
game.fabricate.api.managerExtensions.setWorldNavTabBadge('downtime', 'board', null);
setWorldNavTabBadge(surfaceId, tabId, badge) returns true when a provider currently holds surfaceId and declares tabId, and false otherwise, storing nothing. A malformed badge throws a TypeError and changes nothing — validation runs first, before Fabricate checks whether anything is listening, so a companion feature-detecting the seam gets the same answer regardless of install order.
Resolution is three layers deep, in one fixed order: the runtime badge set through setWorldNavTabBadge, then the tab’s own registered badge, then no badge at all. null clears the runtime layer and falls back to the registered badge. An explicit { count: 0, accessibleName } is a stated zero and does not fall back, the same rule an empty actions array follows for Runtime Route Chrome.
A badge is scoped to the registration, not to a mount — this is the opposite lifetime from runtime route chrome. Route chrome is cleared the moment a mount ends; a badge’s whole job is to be true while your companion is not mounted, so it survives mount, unmount, tab change, route change and window state. It is dropped only when your provider itself leaves the registry, so unregistering and re-registering starts a tab back at its own registered badge, with no stale runtime value left over.
The badge is announced as a description, never as a name. Fabricate renders it with role="img" and your accessibleName, points the rail sub-item’s aria-describedby at it, and leaves the sub-item’s own accessible name as the tab’s accessibleName. When no badge is set — including right after a runtime badge is cleared with null — the sub-item carries no aria-describedby at all, so nothing is left pointing at a description that is not there.
Core also sums the resolved badge counts of every tab the rail renders onto the Downtime parent row, as a single summary mark, while that group is collapsed or the rail is collapsed. That rollup is Core’s arithmetic over your numbers, it replaces the rail’s muted PREMIUM chip for as long as it shows, and for most GMs — whose Downtime disclosure is closed on every fresh Manager open — it is the only place your count is ever seen.
The Mount Context
mount({ target, tabId, context }) must be synchronous and return either one cleanup function or nothing. tabId is always one of the provider’s own tab ids. context is a frozen object carrying no Fabricate store, document, or component:
| Field | Meaning |
|---|---|
schemaVersion | Context contract version, currently 1. |
surface | The Fabricate application hosting the provider; currently always 'manager'. |
surfaceId | The surface id this provider was registered under. |
route | The Manager route rendering the provider, e.g. 'world-downtime'. |
tabId | The active tab id, identical to mount’s own tabId argument. |
craftingSystemId | The Manager’s selected crafting system id, or null. The route is reachable with no system selected, so handle null. |
isGM | Whether the current Foundry user holds the GM role. This is presentation information, not authorization — gate your own writes. |
revision | Increments on every requestRemount() call. |
requestRemount() | Ask Fabricate to re-render this surface. It runs the current cleanup, clears the target, and calls mount again with a fresh context. |
setRouteChrome(chrome) | Restate this mount’s route chrome at any time, with no remount. See Runtime Route Chrome. |
onRouteReselect(handler) | Register a handler for the GM re-activating the rail sub-item this mount is already showing. See Runtime Route Chrome. |
onBeforeNavigate(handler) | Register a veto over the navigations that would end this mount. See Guarding Unsaved Work. |
navigateToTab(tabId) | Take the GM to another of your own registered tabs. See Navigating To Your Own Tabs. |
A new context object is created — never mutated — whenever one of its values changes, which also remounts the active tab. setRouteChrome, onRouteReselect, onBeforeNavigate and navigateToTab are the exceptions: they are functions carried on that same frozen context, and calling them never changes the context’s own identity, so none of them triggers the remount a new context would.
Runtime Route Chrome
A tab’s title, subtitle, breadcrumb, actionsLabel and actions are read once, at registration. That is enough for a companion whose tab is a single screen. It is not enough for a tab that is a list drilling into an editor. The editor needs its own title, its own artwork, an “Unsaved” chip, and Back, Delete and Save actions in the same header, without losing the mounted editor state underneath.
context.setRouteChrome(chrome) restates this mount’s chrome at any time, with no remount. It accepts the same fields a tab may register, plus icon and image for a header medallion, and status for a chip:
mount({ target, tabId, context }) {
const view = mountCompanionDowntime({ target, tabId, context });
view.onOpenProject((project) => {
context.setRouteChrome({
title: project.name,
subtitle: game.i18n.localize('MY_MODULE.Downtime.Projects.EditingSubtitle'),
status: view.isDirty()
? { label: game.i18n.localize('MY_MODULE.Unsaved') }
: undefined,
actions: [
{ id: 'back', label: game.i18n.localize('MY_MODULE.Back'), icon: 'fas fa-arrow-left',
tone: 'ghost', onSelect: () => view.closeProject() },
{ id: 'delete', label: game.i18n.localize('MY_MODULE.Delete'), icon: 'fas fa-trash',
tone: 'danger', onSelect: () => view.deleteProject(project.id) },
{ id: 'save', label: game.i18n.localize('MY_MODULE.Save'), icon: 'fas fa-check',
tone: 'primary', onSelect: () => view.saveProject() },
],
});
});
// Back to the list: drop the runtime layer and let the tab's own registered
// chrome show through again.
view.onCloseProject(() => context.setRouteChrome(null));
const stop = myDowntimeStore.subscribe(() => context.requestRemount());
return () => { stop(); view.destroy(); };
},
Resolution runs three layers deep, in one fixed order: the live mount’s runtime chrome, then the active tab’s registered chrome, then Fabricate’s own string. A companion that never calls setRouteChrome reads exactly as it did before this channel existed. An omitted field falls through to the next layer down. It does not clear that field.
A call replaces, it never merges. Each call states the whole chrome, so an omitted field falls back to the layer below and there is no partial update. Pass null (or {}) to drop the runtime layer entirely and restore the tab’s own registered chrome, as the worked example does on close.
actions resolves with ??, not ||. An empty array means “this screen has no actions” and stays empty rather than falling through to the tab’s own list. A truthiness check would erase exactly the distinction an editor’s Back, Delete and Save need from its list screen’s actions.
Unknown keys are refused, not ignored. A registered tab silently ignores a field it does not read, but a runtime update throws a TypeError on any key outside the documented set, including a misspelling such as subtitel. Nothing applies until validation passes, so a refused update leaves the header showing whatever it already showed.
Artwork is opt-in and off by default. icon and image have no registration-time counterpart, so the route’s header carries no medallion until a companion sets one. icon is a Font Awesome class string and image is an image path. The two are mutually exclusive, and declaring both throws.
status renders Fabricate’s own unsaved-style chip. It is { label, tone?, tooltip? }. tone defaults to warning, Fabricate’s own staged-changes tone, and also accepts info, positive, active, neutral, danger, negative and disabled.
Localization stays your responsibility. As at registration, Fabricate renders every string a runtime update carries exactly as supplied.
A stale mount cannot repaint the screen. setRouteChrome returns false, and changes nothing, once its mount has ended: a tab switch, an unregister, or the GM leaving the route all end it. A companion holding a context from a late-resolving promise or a stray listener cannot dress a screen the GM has since moved on from.
Updating chrome never remounts. This is the property the whole channel exists to preserve. The mount context’s identity, which is what a remount is keyed on, never changes when setRouteChrome is called, so your editor’s own state, scroll position and focus are untouched.
context.onRouteReselect(handler) registers a handler for the GM clicking the rail sub-item of the tab your mount already shows. Before this channel existed, that click did nothing, because Fabricate had no lower level to navigate to. Now it is offered to your mount, so a list-then-editor companion can treat it as “pop back to the list”:
mount({ target, tabId, context }) {
const view = mountCompanionDowntime({ target, tabId, context });
const stop = context.onRouteReselect(() => view.closeProject());
return () => { stop(); view.destroy(); };
},
The call returns an idempotent unsubscribe function, and Fabricate also drops the handler itself when the mount ends, so an unstopped subscription is not a leak. A throwing handler is caught and logged, and never breaks the rail click for anyone else.
onRouteReselect is deliberately not routed through Fabricate’s own route-exit confirmation. No Manager route is being exited by this click, so there is nothing for that confirmation to guard. Whether your companion’s own unsaved editor state should block the pop is your question to answer inside the handler.
Guarding Unsaved Work
Fabricate’s own editors refuse to be navigated away from with unsaved changes: leaving the recipe editor with a dirty draft raises a discard prompt, and so does closing the Manager window. A companion could not do the same. It could prompt on the controls it owns — its own Back action, and the rail re-activation onRouteReselect hands it — but it had no say at all when the GM switched to another tab, left the route, or closed the window. The panel was disposed and whatever was in it went with it.
context.onBeforeNavigate(handler) registers your mount’s veto over exactly those three navigations:
mount({ target, tabId, context }) {
const view = mountCompanionDowntime({ target, tabId, context });
const stop = context.onBeforeNavigate(async ({ reason }) => {
if (!view.isDirty()) return true;
// `reason` is 'tab', 'route' or 'close'. Keeping a draft for the session is only an
// answer for the first two — on 'close' the session is what is ending.
const confirmed = await foundry.applications.api.DialogV2.confirm({
window: { title: game.i18n.localize('MY_MODULE.Downtime.Discard.Title') },
content: `<p>${game.i18n.localize('MY_MODULE.Downtime.Discard.Content')}</p>`,
});
if (confirmed) view.discardDraft();
return confirmed;
});
return () => { stop(); view.destroy(); };
},
Return false to keep the GM where they are. Anything else allows the navigation, including returning nothing at all. That asymmetry is deliberate: a handler you wrote to watch navigations cannot trap the GM by forgetting a return. The handler may be synchronous or async, and Fabricate awaits a promise, because the answer normally comes from a dialog.
Three navigations are covered, and they are named.
reason | What the GM did |
|---|---|
'tab' | Activated the rail sub-item of a different tab of your provider. |
'route' | Left the Downtime route entirely — another rail item, another Manager screen. |
'close' | Closed the Manager window. |
The event carries reason and nothing else. Your own tabId is already on the context you closed over, and the destination is withheld on purpose: Fabricate normalizes a route after your guard has answered, so a decision made from a destination would be a decision made from a value that can still change.
Several things are deliberately not covered, and your own fallback still has to hold for them. A browser reload and a Foundry logout never reach this seam at all. Neither does a remount — whether you asked for one with requestRemount() or a context value such as the selected crafting system changed — because a remount is not the GM leaving your screen, and you see it as a fresh mount either way. Neither does re-entering the route or the tab you are already on: those navigate nowhere, and re-activating the tab on screen stays onRouteReselect’s, where any prompt about your unsaved work belongs inside your handler.
A forced close is never guarded. Foundry’s own lifecycle teardown closes the Manager with force, in contexts where no dialog can be serviced, and so does Fabricate’s smoke harness. A guard that ran there would hang the window on a question nothing can answer, so force skips it exactly as it already skips Fabricate’s own dirty-draft guards.
A throwing guard allows the navigation. It is caught and logged, and the GM goes where they were going. The opposite ruling would let one bug in your module leave a GM on a route they cannot leave and in a window they cannot close, recoverable only by reloading Foundry — and it would do it silently. Allowing degrades to exactly the behaviour you had before this seam existed, so nothing is destroyed that was not already at risk.
A second navigation during a pending answer shares that answer. If the GM clicks the rail and then the window’s close button while your dialog is still open, your handler is not called again. Both navigations resolve from the one decision the GM makes, and each then continues on its own. So you never have to defend against your own dialog being opened twice.
A companion that never calls onBeforeNavigate is unaffected. No prompt, no added await, no changed timing: Fabricate takes the same code path it took before this channel existed.
Your guard dies with your mount. The call returns an idempotent unsubscribe, and Fabricate drops the handler itself when the mount ends, so an unstopped subscription is not a leak. A context you kept from an ended mount registers nothing.
Navigating To Your Own Tabs
A companion can draw a control that names another of its screens — “change this in Settings” on the card where the GM feels the setting’s effect — and, until this call existed, could not reach it. The active tab is Fabricate’s own state and nothing published a way into it, so such a control was either absent or dead.
context.navigateToTab(tabId) takes the GM to another of the tabs your provider registered:
autoAdvanceCard.onEditSettings(() => {
// The same navigation the GM's own click on your Settings rail sub-item performs.
context.navigateToTab('settings');
});
It is your rail sub-item’s own click. Asking for the tab already on screen re-activates it through onRouteReselect rather than remounting. Any other tab is offered to your own onBeforeNavigate guard with reason: 'tab', so unsaved work can still stop it. And an allowed move expands the rail group and activates the view exactly as a click does. Your programmatic request and the GM’s click are one navigation, not two that agree today.
It returns true when the request was honoured and false when it was refused, and a promise of either whenever your guard answers asynchronously — a veto may be a dialog, and a synchronous true would be a claim about a question still on screen. A re-activation counts as honoured: nothing moved because nothing had to.
You can reach your own tabs and nothing else. Another provider’s surface, a Fabricate route, and an id your provider never declared are all refused. Membership is resolved from what you have registered, not from what Fabricate happens to be rendering, so an id you have just unregistered is refused rather than resolving against Fabricate’s own fallback tabs.
A well-formed id you did not register returns false; a malformed one throws. Your tab set is a runtime fact — you may re-register with a different one, and a conditional tab may not exist yet — so asking for an id that is not currently yours is a question rather than a coding error. A non-string or empty id never is: it raises a TypeError and changes nothing, exactly as a malformed setRouteChrome update does. A call from a context whose mount has ended returns false and moves nobody.
Do not call it from inside your own onBeforeNavigate handler. “Veto this move, and send the GM to Settings instead” is the tempting shape, and it returns false from there: the request is not the question your guard is being asked, so Fabricate refuses it rather than nesting one navigation inside the answer to another. Redirect after you have answered — from the continuation of your own dialog, say — because a redirect is a consequence of the decision rather than part of making it. The same refusal covers the window in which a promise your guard returned is still pending.
Two things that are not refusals. Your context is already live for the duration of mount() itself, so a call from inside mount re-enters Fabricate’s routing mid-mount; redirect from your first data callback instead. And asking for the tab already on screen runs your onRouteReselect handler synchronously, before the call returns — so if that handler tears down what you are standing in, it has already done so by your next line.
The Panel’s Layout Contract
Everything in this subsection describes provider mode only. Fabricate’s own read-only preview keeps its inset, its scroller, its tab strip and its collapsible rail; none of it changes.
The panel is a bare box. The element handed to mount is a div at the full height of the Manager’s content pane, with no padding, background, scroller or containment of its own. The companion supplies its own inset. Fabricate’s 12px 20px 24px inset is gone as of this contract: a companion that shipped against it must add the equivalent padding to its own root.
Your tabs are rail items, and Fabricate renders no tab strip. A provider’s tabs appear once, as sub-items of the Manager rail’s Downtime group, and the panel below them is a named region rather than a tab panel. The region takes the tab’s visible label as its name — it is labelled by the sub-item’s label element, not by the sub-item itself, so a landmark is named after the screen rather than after the action that opens it. The sub-item itself carries accessibleName as its aria-label and tooltip as its native tooltip; see the field table above for where each one lands. The rail is locked expanded while a provider holds this route, so those sub-items are always reachable; the rail’s collapse control renders disabled and explains itself, and the GM’s stored collapse preference is left untouched and restored on leaving the route. Entering the route scrolls the active sub-item into view, so the current screen’s rail item is visible without hunting for it.
Overflow. Core’s panel scroller keeps working for any companion whose content overflows its root visibly — including one that takes the full height. It stops rescuing a companion the moment that companion absorbs its own content: by giving its root a non-visible overflow, or by letting a definite-height flex or grid root shrink its children, which squashes them rather than scrolling them. Height alone does not remove the fallback. A companion that intends to own its layout should own its scroller explicitly rather than infer one from its height.
The block size is definite at every Manager width, and the inline size is not guaranteed. height: 100% on your own root resolves against a real height at every window size, because this route opts out of the shared narrow-width stack that turns the Manager body content-sized. The inline size makes no such promise: Fabricate enforces no minimum Manager window size and makes no no-horizontal-overflow guarantee for this panel — explicitly unlike the player seam, which is guaranteed at the player window’s enforced 1024x640 floor. Measured across an ordinary width ladder the target’s inline size runs from about 1178px down to about 378px. Responsive behaviour inside the target is yours; if you want container queries, declare container-type on your own root.
position: fixed positions against the viewport unless your own root contains it. The Manager root’s container-type: inline-size does not make it the containing block for fixed-position descendants; contain: layout or a transform on your own root does. Anchor your popovers to your own root instead of assuming viewport coordinates.
isolation: isolate caps z-index escape. The Manager root creates a stacking context, so an element inside your panel at the maximum z-index still loses to a body-level element at z-index: 100. Content that must paint above anything outside the Manager has to be portalled outside the Manager element, which is what Fabricate’s own popovers and pickers do.
Theme tokens are inherited, not stamped. Foundry stamps the theme attribute on the document element and on Fabricate roots that exist when it runs; the Manager mounts lazily and carries no attribute of its own, inheriting purely by cascade. Read the --fab-* custom properties live and your surface re-skins with no remount; snapshot their values into JavaScript at mount and it will not. Content you render outside the Manager subtree, such as your own dialogs, inherits the document’s tokens rather than the Manager’s.
Keyboard. Once you own the scrolling, the panel is no longer the nearest scrollable ancestor, so any scroll container you create must be reachable and operable from the keyboard.
When The Surface Is Absent
A Manager surface Fabricate does not render is not an error, and it is not something your module can detect at registration time.
Today this has one cause: the downtime surface is gated behind fabricate.experimentalFeatures, a world setting that is off by default, because the premium Downtime Studio it hosts has not been released yet. The gate is temporary and goes away when the Studio ships.
What still happens, exactly as it would with the gate open.
registerWorldNavProvider(provider)validates and stores your provider, returns your unregister function, and throws nothing. A GM’s world setting is not something a module registering atreadycould know, so it is never treated as your fault: Fabricate logs no error, raises no warning, and shows no notification.fabricate.manager.navProviderRegisteredfires with your surface id and tab ids.- The Manager title bar’s
PREMIUMbadge lights, because it reports that a companion module is registered rather than that any particular route is on screen.
What you observe instead is an absence.
mount({ target, tabId, context })is never called, so you receive no context, no target, and no cleanup call.- None of
fabricate.manager.surfaceMounted,fabricate.manager.surfaceUnmountedorfabricate.manager.surfaceTabChangedfire for the surface. - The Manager rail shows no
Downtimeentry, and the route cannot be reached.
A gate that closes under a live mount does not touch your mount. The setting is a world setting, so a GM can turn it off while your panel is on screen. When that happens the rail entry disappears, but your panel stays exactly where it is: your mount is not torn down, your cleanup does not run, your guard is not called, and your unsaved work is untouched. Fabricate will not discard a GM’s in-progress edit because a setting changed.
The GM leaves that panel whenever they next navigate, and that is the ordinary guarded exit described above — your onBeforeNavigate guard is called with reason: 'route', a false keeps them there, and an allowed exit runs your cleanup once with the target still connected. Once they have left, the route is gated behind them and they cannot come back to it.
requestRemount() does not bring back a surface the gate has removed. Calling it from a context you retained across the gate closing is safe and does nothing; there is no host to re-render.
Nothing here applies to the player window, which hosts no Downtime surface and is not affected by this setting.
Lifecycle And Failure
Fabricate calls the returned cleanup exactly once before switching tabs, replacing or unregistering the provider, leaving the route, or closing the Manager, and always while the target is still connected. A mount or cleanup error is caught, logged, and contained: partial content is cleared and Fabricate’s own preview takes the whole surface back — panel, tab strip, and rail entries alike — until the next registration. When a provider registers, unregisters, or re-registers with a different tab set, an active tab id the new set no longer declares falls back to that set’s first tab, so the route never renders an empty panel. When such a change removes the node that held focus, Fabricate moves focus to whichever element names the active screen in the mode now live — your panel region in provider mode, its own tab button in the preview — rather than dropping it to the document body. It does that only when focus was inside the route’s panel, so ordinary rail navigation is left alone; move focus yourself from your own mount if you want it somewhere more specific. The companion owns all authorization, localization, domain data, persistence, and resources it creates; Fabricate supplies only the target and Manager shell.
Manager Hooks
Fabricate publishes observational hooks around these events, exposed on game.fabricate.api.HOOKS.manager so you do not have to hard-code the strings. They are notifications only: a listener’s return value is ignored and nothing a listener does changes what the Manager renders. To change the Manager, register a provider.
| Hook | Fires | Payload |
|---|---|---|
fabricate.manager.navProviderRegistered | A provider takes a surface | { schemaVersion, surfaceId, tabIds } |
fabricate.manager.navProviderUnregistered | A provider releases a surface | { schemaVersion, surfaceId, tabIds } |
fabricate.manager.surfaceMounted | The Manager route hosting a surface renders | { schemaVersion, surfaceId, route, tabId, providerId, coreFallback } |
fabricate.manager.surfaceUnmounted | That route is torn down | { schemaVersion, surfaceId, route, tabId, providerId, coreFallback } |
fabricate.manager.surfaceTabChanged | The active tab changes | { schemaVersion, surfaceId, route, tabId, previousTabId, providerId, coreFallback } |
Hooks.on(game.fabricate.api.HOOKS.manager.SURFACE_TAB_CHANGED, ({ surfaceId, tabId }) => {
console.log(`Fabricate manager surface ${surfaceId} moved to ${tabId}`);
});
Player Navigation Extension
Companion modules can add their own top-level tabs to Fabricate’s player window through the API-v1 player extension seam. The seam is general and keyed by surface id; it is not a downtime feature, and Downtime is only its first consumer.
The two seams differ in what they do, and the difference is structural rather than cosmetic. A Manager provider replaces one Core route’s content. A player provider adds N tabs to the player window’s navigation rail, alongside Crafting, Alchemy, Gathering, Journal and Inventory. Fabricate renders every registered player surface, with one temporary exception: the downtime surface, which is gated behind the same world setting as the Manager’s Downtime route. No surface id is privileged into being rendered, and Fabricate never checks an id against a list of ids it will accept.
The
downtimesurface may not be present here either. While the premium Downtime Studio is unreleased, a companion’sdowntimetabs are shown in the player window only when the world settingfabricate.experimentalFeaturesis on, which it is not by default. Registration is unaffected and never fails because of it. See When the player surface is absent.
A player surface id is the registering provider’s own id. Fabricate’s player window has no route of its own to name a surface independently, so surfaceId and providerId are always equal — in the mount context and in every hook payload. Both are carried anyway, so a player payload is shape-identical to a Manager one and a listener can read either seam’s events with one handler.
Declare Fabricate as a required module dependency in the companion manifest, exactly as for the Manager seam.
{
"relationships": {
"requires": [{ "id": "fabricate", "type": "module" }]
}
}
The Load Contract, And Why The Fallback Is Armed Inside init
Attempt registration once from the companion’s own init callback. If the API is not there yet, arm one idempotent Hooks.once('ready', …) fallback — and arm it from inside init, never at the module’s ESM top level.
That placement is load-bearing and the reason is Foundry’s script ordering. Module esmodules are sorted by priority, and library-flagged modules evaluate before ordinary ones. A library-flagged companion therefore evaluates before Fabricate does, so a Hooks.once('ready', …) armed at its ESM top level is registered ahead of Fabricate’s own ready listener and fires before the API exists — defeating the one scenario the fallback is there for. Arming it from inside init puts it after Fabricate’s, because by then every module’s init has been dispatched in priority order.
relationships.requires governs dependency availability and activation. It does not establish ordinary-module script priority. The one-shot ready fallback is therefore part of the load contract for both seams. Do not replace it with an order assumption, a render hook, or DOM patching.
Worked Example
let unregisterPlayerDowntime = null;
let playerReadyFallbackArmed = false;
// The provider declares its OWN tabs. These ids are the companion's, not Fabricate's, and they
// can never collide with a Core tab id: Fabricate addresses a provider tab by a namespaced
// route key composed from the surface id and the tab id.
const PLAYER_TABS = [
{ id: 'board', icon: 'fas fa-chart-simple', key: 'Board' },
{ id: 'projects', icon: 'fas fa-list-check', key: 'Projects' },
{ id: 'ledger', icon: 'fas fa-scroll', key: 'Ledger' },
];
function tryRegisterPlayerDowntime() {
if (unregisterPlayerDowntime) return true;
const register = game.fabricate?.api?.playerExtensions?.registerPlayerNavProvider;
if (typeof register !== 'function') return false;
unregisterPlayerDowntime = register({
apiVersion: 1,
id: 'downtime',
tabs: PLAYER_TABS.map(({ id, icon, key }) => ({
id,
// The WHOLE Font Awesome class list, rendered verbatim.
icon,
// Final display text, already localized by the companion.
label: game.i18n.localize(`MY_MODULE.Downtime.${key}.Label`),
// Optional. It REPLACES the button's accessible name, so it must contain the visible label.
accessibleName: game.i18n.localize(`MY_MODULE.Downtime.${key}.Accessible`),
// Optional. Exposed through `aria-describedby`.
tooltip: game.i18n.localize(`MY_MODULE.Downtime.${key}.Tooltip`),
})),
mount({ target, tabId, context }) {
const view = mountCompanionPlayerDowntime({ target, tabId, actorId: context.actorId });
// Re-render this surface whenever the companion's own data changes.
const stop = myDowntimeStore.subscribe(() => context.requestRemount());
return () => { stop(); view.destroy(); };
},
});
return true;
}
Hooks.once('init', () => {
if (tryRegisterPlayerDowntime() || playerReadyFallbackArmed) return;
playerReadyFallbackArmed = true;
// Armed HERE, inside `init` — not at this file's top level. See the load contract above.
Hooks.once('ready', tryRegisterPlayerDowntime);
});
Provider Contract
registerPlayerNavProvider(provider) returns an idempotent unregister function. Call it when disabling the companion; its tabs leave the rail, and Fabricate renders no placeholder in their place.
| Field | Required | Meaning |
|---|---|---|
apiVersion | yes | Must be exactly 1. |
id | yes | The surface id this provider claims, and the surface id Fabricate keys on. Lowercase letters, digits and hyphens, 1–64 characters, starting with a letter or digit. One provider per surface id — registering a second for the same surface throws. |
tabs | yes | One or more tabs, rendered in array order after Fabricate’s own five. |
mount | yes | Synchronous mount callback. |
The player seam recognises no route chrome and no header actions. The player window has no route header, breadcrumb trail or header-action group, so title, subtitle, breadcrumb, actionsLabel and actions are not validated and not read. Fabricate reads only the documented tab fields below: any other field on a tab is ignored, including a count — a nav count badge is Core’s own and is not offered to a provider.
Each entry in tabs:
| Field | Required | Meaning |
|---|---|---|
id | yes | Unique within the tab set, and the same charset as the provider id. Fabricate never checks it against a list of its own, and it can never collide with a Core tab id. |
label | yes | Final visible tab label, rendered verbatim. Localize it yourself: Fabricate localizes only its own five labels. |
icon | yes | The full Font Awesome class list, for example fas fa-scroll, rendered verbatim. Fabricate prefixes the family only for its own tabs, so do not omit it. |
accessibleName | no | Accessible name for the rail button. It REPLACES the visible label as the accessible name, so it must contain the label’s text. |
tooltip | no | Description exposed through aria-describedby. |
The visible rail label truncates with an ellipsis inside its fixed-width button; the untruncated wording is what accessibleName and tooltip are for.
The Player Mount Context
mount({ target, tabId, context }) must be synchronous and return either one cleanup function or nothing. tabId is always the provider’s own bare tab id, never the composed route key.
That composed key is ext:<surfaceId>:<tabId>, and Fabricate addresses every provider tab by it rather than by the bare tab id. That is what makes a collision with a Core tab id structurally impossible without Fabricate learning a single provider id. The route key is what the window’s active-tab state, the rail button’s selection attribute, and the window’s tab query all carry, so it is also the value you pass to open one of your own tabs yourself:
// The worked example's provider id is 'downtime' and one of its tab ids is 'projects'.
game.fabricate.api.getFabricateAppClass().show('ext:downtime:projects');
The window falls back to its Crafting tab when the key names a tab no registered provider currently offers, so register before you call it.
context is a frozen object carrying no Fabricate store, document, or component:
| Field | Meaning |
|---|---|
schemaVersion | Context contract version, currently 1. |
surface | The Fabricate application hosting the provider; always 'player'. |
surfaceId | The surface id this provider was registered under, which is the provider’s own id. |
tabId | The active bare tab id, identical to mount’s own tabId argument. |
actorId | The player window’s shared Actor selection, or null when nothing is selected. A change of actor produces a new context and therefore a remount. |
isGM | Whether the current Foundry user holds a GM role. This is presentation information, not authorization — it is also true for assistant GMs, and this window has no role gate at all, so gate your own writes. |
revision | Increments on every requestRemount() call. |
requestRemount() | Ask Fabricate to re-render this surface. It runs the current cleanup, clears the target, and calls mount again with a fresh context. |
A new context object is created — never mutated — whenever one of its values changes, which also remounts the active tab. The converse holds too, and you can rely on it: while none of the values above changes, the context keeps its identity and your surface is not remounted. So opening the window, another companion registering or unregistering, and any other republication that leaves your surface’s values alone all leave your mounted content in place, with its scroll position, focus, and in-flight state intact.
The Panel’s Layout Contract
The element handed to mount is a bare div inside the player window’s content area, and it declares exactly height: 100%; min-height: 0 and nothing else. Each omission is deliberate, and a companion can rely on all three:
- No scroller. The player window’s content area already scrolls, and a second scroller inside it produces a nested double scroll.
- No CSS container. A companion that wants container queries declares one on its own root. A fixed-position element inside the target positions against the viewport.
- No padding or background. The companion owns its own inset and surface.
Give your own root height: 100%; min-height: 0 too. Skip it and your root resolves against auto and falls back to content height rather than filling the panel, and nothing reports it. If you want container queries, declare container-type on your own root — its inline size is the target’s, so you measure the same box without Fabricate imposing containment on companions that do not want it.
When The Player Surface Is Absent
A player surface Fabricate does not render is not an error, and it is not something your module can detect at registration time.
Today this has one cause, and it is the same one as on the Manager side: the downtime surface is gated behind fabricate.experimentalFeatures, a world setting that is off by default, because the premium Downtime Studio it hosts has not been released yet. The gate is temporary and goes away when the Studio ships. It names that one surface id: register any other id and your tabs render on registration alone, whatever the setting says.
What still happens, exactly as it would with the gate open.
registerPlayerNavProvider(provider)validates and stores your provider, returns your unregister function, and throws nothing. A GM’s world setting is not something a module registering atreadycould know, so it is never treated as your fault: Fabricate logs no error, raises no warning, and shows no notification.fabricate.player.navProviderRegisteredfires with your surface id and tab ids.- The Manager title bar’s
PREMIUMbadge lights, because it reports that a companion module is registered at all — a player-window-only surface lights it too.
What you observe instead is an absence.
mount({ target, tabId, context })is never called, so you receive no context, no target, and no cleanup call.- None of
fabricate.player.surfaceMounted,fabricate.player.surfaceUnmountedorfabricate.player.surfaceTabChangedfire for the surface. - Your tabs are absent from the player window’s rail, and no route key addressing them can be selected. The player window shows nothing in their place: it carries no premium signal in any state, so a gated surface and an uninstalled companion look identical.
When a change to the setting takes effect.
The gate is read whenever Fabricate derives its surface snapshot — when the player window opens, and on every registration, unregistration or re-registration. It is not pushed into an already-open window. A player standing on your tab when a GM turns the setting off keeps the screen they are on until the window is reopened or a registration re-derives the rail, which is deliberate: evicting them would run your cleanup and discard whatever they had in progress because a world setting moved. Until then that window’s rail may still show your tabs, but selecting one is refused — the tab a player is already on stays put, and a move back to it is declined rather than rendering an empty panel. Turning the setting on needs no re-registration from you — the registration Fabricate has been holding renders at the next snapshot.
Lifecycle And Failure
Fabricate calls the returned cleanup exactly once, while the target is still connected, and before whatever ended the mount removes it. That holds on every path that ends a mount: a tab change within your own surface, a tab change away to a Core tab, a tab change to a different companion’s surface, your provider unregistering while one of its tabs is live, and the window closing. It holds for a selection Fabricate makes on the user’s behalf as well, such as the fallback described below. Fabricate reaches the disposal from outside your mounted subtree and before the state change that removes it, and the disposal is idempotent, so a second caller reaching it does not run your cleanup twice. On window close the player application disposes first, then unmounts its Svelte root, and only then does ApplicationV2 remove the window element.
A mount or cleanup error is caught, logged, and contained, and the containment is deliberately legible rather than silent:
- partial content is cleared;
- the faulted surface’s rail entries stay, and the active tab does not move;
- Fabricate renders its own error state in the panel, naming the provider that failed;
- the registration survives — the provider is set aside, never unregistered — so a later mount may succeed without the companion re-registering, on the conditions spelled out below;
- focus is recovered onto the surface’s rail button rather than dropping to the document body.
The fault is recorded against the whole surface, not against the tab that threw. It is keyed on the (surfaceId, provider) pair, so once one of your tabs fails to mount, selecting any other tab of the same provider shows the same error state and Fabricate does not attempt another mount for it. That is deliberate containment rather than a per-tab retry: Fabricate cannot distinguish a tab-specific failure from a broken provider, and retrying the siblings of a provider that has already thrown would just repeat the fault. Two things clear it, and neither of them is a retry Fabricate performs on its own.
The first is a new snapshot carrying a different provider object for the surface, which is what “a later snapshot may mount” means above. Unregistering and re-registering is such a snapshot only when the second registration passes a different object: a companion that re-registers the same module-level singleton hands Fabricate a provider that is still === the recorded one, so the fault and its error state survive. Register a freshly built provider object when you want the surface retried.
The second is the user closing and reopening the player window. The record of which providers have faulted belongs to that window and is discarded when the window is torn down, so the next open mounts your provider again even though it is the same object. That is the retry Fabricate’s own error state offers the user, and it is why a fault caused by a transient condition does not strand the surface until the world reloads. Bringing an already-open window back to the front is not a reopen and clears nothing.
When a provider registers, unregisters, or re-registers with a different tab set, an active route key the new set no longer offers falls back to Fabricate’s default Crafting tab, so the window never renders an empty panel.
The companion owns all authorization, localization, domain data, persistence, and resources it creates; Fabricate supplies only the target and the window shell. Note that the player window applies no per-user visibility or permission gate to a provider tab: unlike the Manager, it has no GM gate, so two players never see different rails. The one gate that exists is world-scoped and temporary, and it is described below.
Player Hooks
Fabricate publishes observational hooks around these events, exposed on game.fabricate.api.HOOKS.player so you do not have to hard-code the strings. They are notifications only: a listener’s return value is ignored and nothing a listener does changes what the player window renders.
surfaceId and providerId are always equal in these payloads, for the reason given above. There is no coreFallback field: Fabricate renders no content in a provider’s place on this surface, so a tab exists only while its provider does.
| Hook | Fires | Payload |
|---|---|---|
fabricate.player.navProviderRegistered | A provider claims a player surface | { schemaVersion, surfaceId, tabIds } |
fabricate.player.navProviderUnregistered | A provider releases a surface | { schemaVersion, surfaceId, tabIds } |
fabricate.player.surfaceMounted | The player window mounts a surface | { schemaVersion, surface, surfaceId, tabId, providerId } |
fabricate.player.surfaceUnmounted | That surface is torn down | { schemaVersion, surface, surfaceId, tabId, providerId } |
fabricate.player.surfaceTabChanged | The active tab of a mounted surface changes | { schemaVersion, surface, surfaceId, tabId, previousTabId, providerId } |
Hooks.on(game.fabricate.api.HOOKS.player.SURFACE_TAB_CHANGED, ({ surfaceId, tabId }) => {
console.log(`Fabricate player surface ${surfaceId} moved to ${tabId}`);
});
Published UI Components
game.fabricate.api.ui lets a companion draw a Fabricate primitive into an element the companion owns, so it renders Fabricate’s own component instead of keeping a copy. It is the other direction from the two navigation seams: they put a companion’s content into Fabricate’s windows, and this puts Fabricate’s components into the companion’s.
Do not destructure it as
const { ui } = game.fabricate.api, because that shadows Foundry’s ownuiglobal. Useconst fabUi = game.fabricate.api.uiinstead.
Feature-detect it at the point of use, and never hold an api reference taken at init, because Fabricate rebuilds game.fabricate.api at ready:
const fabUi = game.fabricate?.api?.ui;
if (fabUi?.schemaVersion !== 1) return; // Absent, or a shape this companion does not know.
if (!fabUi.components.includes(name)) return; // Not published by this Fabricate version.
const handle = fabUi.mount(name, { target: element, props }); // `props` as `describe(name)` lists.
handle.update(nextProps); // Replaces every prop but an omitted value prop; it never merges.
handle.destroy(); // Required on every path that ends the mount.
A worked mount, in an ApplicationV2 of your own, names a Meter and keeps its handle:
#meter = null;
_onRender(context, options) {
super._onRender(context, options);
const fabUi = game.fabricate?.api?.ui;
if (fabUi?.schemaVersion !== 1 || !fabUi.components.includes('Meter')) return;
const target = this.element.querySelector('[data-hp-meter]'); // An empty element you own.
this.#meter?.destroy(); // A re-render replaced the old target.
this.#meter = fabUi.mount('Meter', {
target,
props: { label: 'Hit points', value: 14, max: 20, valueText: '14 of 20 hit points' },
});
}
async _preClose(options) {
this.#meter?.destroy();
await super._preClose(options);
}
Draw the visible reading yourself, because Meter draws no figure. A later change goes through this.#meter.update({ ... }) with every prop again.
A required prop that names or labels a control, ariaLabel, label, title or legend, with no other prop that states its own rule, is refused when it is not a string or is white space alone, with <Component> requires a non-blank string "<prop>", so a control is never mounted with no name or with a wrong one such as true. An empty or absent one is refused as before, with <Component> requires a non-empty "<prop>". This is not a narrowing under the versioning rule: each such prop’s section states it as final display text naming the control, so a non-string or a string of white space alone was already outside its accepted values. Pass a name written out in words, never white space or a non-string.
The published components, in publication order:
| Component | Version | Root | Props | Rest |
|---|---|---|---|---|
TierTrack | 1 | any | tiers (required), currentIndex, direction, layout, ariaLabel (required), currentLabel (required), reachedLabel (required), aheadLabel (required), hint | yes |
Avatar | 1 | any | art, name (required), alt, size, shape, tint, icon | no |
Medallion | 1 | any | art, icon, size (required), alt, tint, glyph, variant, tone, ink, text | no |
FillBar | 1 | any | value, tone, color, shares, origin, neutralBand, density | yes |
Meter | 1 | any | value, max, segments, valueText, label (required) | yes |
BandedBar | 1 | any | rows (required), direction, density | yes |
StatBox | 1 | any | value (required), label (required), icon, tone, layout, note, children (slot) | yes |
InfoStrip | 1 | any | label (required), facts (required), badge | yes |
Kicker | 1 | any | as, tone, size, for, children (text, required) | yes |
Chip | 1 | any | tone, density, emphasis, icon, mono, struck, truncate, children (text, required), ariaLabel | yes |
Rail | 1 | any | label, children (slot) | yes |
InspectorCard | 1 | any | children (slot), tone, title (text), note (text), leading (slot), trailing (slot) | yes |
EmptyState | 1 | any | icon, title, hint, compact, inline, note, filtered, children (slot) | yes |
Notice | 1 | any | tone, title (required), detail, icon, action, onAction (callback), dismissable, dismissLabel (required when dismissable), onDismiss (callback, required when dismissable), assertive | yes |
Button | 1 | any | role, fullWidth, disabled, size, icon, busy, type, children (text, required), onclick (callback, required), aria-expanded (aria), aria-describedby (aria), ariaLabel, tooltip, pressed, description | yes |
StatusToggle | 1 | any | on (required), ariaLabel, semantics, onclick (callback, required), aria-labelledby (aria), aria-describedby (aria), label (text, required) | yes |
Stepper | 1 | any | value (required), min, max, step, disabled, allowUnset, fill, density, placeholder, format, stops, nullLabel, ariaLabel (required), decrementLabel (required), incrementLabel (required), onChange (callback, required), decrementTooltip, incrementTooltip, size | no |
SearchField | 1 | any | value (value), onValueChange (callback), placeholder, ariaLabel (required), density, countLabel (text) | yes |
Select | 1 | any | options (required), value, onChange (callback, required), ariaLabel (required), placeholder, size, fill | no |
StageBars | 1 | any | stages (required), currentIndex, numbered, gap, track, ariaLabel (required) | yes |
Field | 1 | any | as (required), children (slot), size, face, type, invalid, align, readOnly | yes |
Well | 1 | any | label, children (slot), tone | yes |
Callout | 1 | any | tone, title, text, icon, items, actions (slot), actionsPlacement | yes |
IconButton | 1 | any | icon (required), ariaLabel (required), role, size, disabled, onclick (callback, required), aria-expanded (aria), description | yes |
EditorTabs | 1 | any | tabs (required), activeTab, onSelect (callback, required), ariaLabel (required), idStem (required), activePanelOnly | yes |
RadioCardGroup | 1 | any | options (required), value, onChange (callback, required), legend (required), layout, columns, disabled, disabledOptions, activation | yes |
SegmentedControl | 1 | any | options (required), value, onChange (callback, required), ariaLabel (required), fill, density, tone, shape, surface, size | yes |
Pagination | 1 | any | totalCount (required), pageSize (required), pageIndex, pageSizeOptions (required), onPageChange (callback, required), onPageSizeChange (callback, required), persistent, ariaLabel (required), navLabel (required), previousLabel (required), nextLabel (required), perPageLabel (required), rangeTemplate (required), pageTemplate (required), density, landmarks, perPageAriaLabel | no |
IconPicker | 1 | any | value, onChange (callback, required), ariaLabel (required), listLabel (required), searchLabel (required), searchPlaceholder, noMatchesText (required), tint, iconOnly | no |
ActionMenu | 1 | any | items (required), ariaLabel (required), align, onSelect (callback, required) | no |
Modal | 1 | any | open, title (required), subtitle, icon, size, closeLabel (required), closeOnOutsideClick, trapFocus, initialFocus, footerLayout, scrim, onClose (callback, required), body (slot), footer (slot) | no |
ListRow | 1 | fabricate | name (required), detail, quantity, art, icon, tint, tone, muted, selected, disabled, onOpen (callback), aside (slot), leading (slot), badges (slot), meta (slot), trailing (slot), markSize, density, layout, truncateName, detailAlign, current, busy | yes |
ToggleCard | 1 | any | title (required), sub, icon, on (required), semantics, onToggle (callback, required), tone | no |
SelectionCheckbox | 1 | any | checked (required), indeterminate, disabled, density, label (text, required), ariaLabel, onChange (callback, required), aria-describedby (aria), decorative, tone | yes |
Disclosure | 1 | any | open, onToggle (callback, required), level, disabled, head (slot), body (slot) | yes |
Typeahead | 1 | any | options (required), query (value), onQueryChange (callback), value, onChange (callback, required), ariaLabel (required), placeholder, emptyLabel, allowFree, onFreeText (callback, required when allowFree), density, error, countLabel (text), openOnEmpty | no |
Popover | 1 | any | open, anchorId (required), placement, title (text, required), ariaLabel, closeOnOutsideClick, onClose (callback, required), body (slot) | no |
TintSwatches | 1 | any | value, onChange (callback, required), ariaLabel (required), tints, labels | no |
Each row lists the component’s published props, noting a prop’s kind when it is not plain data, marking a required one and naming the prop while which one is required, and says yes in Rest when it takes data-* attributes. An aria prop is an ARIA attribute Fabricate writes on the component’s control. Root names the Fabricate ancestor the component’s target needs, and any needs none. Fabricate draws Button, IconButton, StatusToggle, InspectorCard, Well, Field, SearchField, Stepper, Select, SegmentedControl, RadioCardGroup, EditorTabs, Pagination, IconPicker, ActionMenu, Modal, ToggleCard, SelectionCheckbox, Disclosure, Typeahead, Popover and TintSwatches under a standalone style root in a target that has no Fabricate root, and refuses them there when target’s root node is a shadow root. See Ownership and theme. Each component’s section states the shape of every prop it publishes; a member or value a section does not state is private. A rest data-* attribute lands on the component’s root, where Foundry reads it too: data-tooltip shows Foundry’s tooltip, and data-action is dispatched by the window’s own click handling, which reserves close, tab and toggleControls. On Button, StatusToggle, IconButton and SelectionCheckbox the rest keys land on the control itself, so data-keyboard-focus, data-action, data-cursor, every data-tooltip name, and the two names Fabricate’s own stylesheet reads off its own buttons, data-validation-focused and data-essence-sort-direction, are refused there. IconButton’s button carries Foundry’s tooltip, so it refuses data-locked as well. Each component’s tone set is its own and the sets are not interchangeable: InfoStrip’s badge says positive where FillBar and Medallion say success. Colour is never the only carrier of a state: wherever you pass a tone, tint, ink, fill or color, say the same thing in text beside the component. A collection of the wrong type, such as rows: null, is a contained fault reported under the component’s name; it is not a refusal.
TierTrack
TierTrack states where a record stands on an ordered set of named tiers. tiers lists each tier as { id?, name, figure?, notes?, valence? } in drawn order: name and figure are final display text, notes is a list of strings drawn in the column layout only, and valence is positive (the default), negative or neutral and colours only a reached tier. currentIndex is the tier the record sits at, and -1 reaches nothing. direction is ascending or descending (highest first). layout is row (badges) or column (a ladder). ariaLabel names the list. currentLabel marks the current tier. reachedLabel and aheadLabel are the hidden state text on every other tier. All four labels are required and already localized. hint is an optional sentence beneath the track. The current tier keeps its valence colour and is marked by a location-dot glyph in row and by the visible currentLabel in column.
Avatar
Avatar draws an actor’s portrait as a fixed-size tile: the artwork, a glyph you name, or the initials of the name. art is an image path, and a falsy one draws icon where it is set and the initials of name where it is not; a path that fails to load draws the browser’s broken image, never the fallback. That path is as Foundry stores it on a document (actor.img, item.img): relative to the Foundry root, or an absolute URL. Pass it unchanged; do not prefix it with / or run it through foundry.utils.getRoute. name is required and is the only source of the initials. alt is read only when art is set, and '' marks the image decorative. size is 26, 28, 30 or 32, the portrait ladder, and defaults to 32. shape is round or square. tint is one of sage, mist, lavender, rose, peach, butter, aqua, mauve, ember, verdant, azure, bone and slate. icon is Font Awesome classes drawn in place of the initials when art is falsy, and is unset by default; it is drawn at 0.4 of size, rounded, in the tile’s own ink. icon takes classes from the sheet the running Foundry ships; a class absent from that build draws an empty box. icon is additive at version 1: a Fabricate that predates it refuses it with "icon" is not a prop of Avatar, which describe(...).props shows. name is never announced and the initials and the glyph are hidden from assistive technology, so a tile without art carries no name: always draw the name as text beside it, and pass alt: '' when you set art. The tile is inline: give its target display: flex, so the tile is a flex item as every Fabricate site draws it.
Medallion
Medallion draws a record’s identity tile: the artwork, or a glyph. art is an image path, and a falsy one draws icon, whose default is fas fa-scroll. That path is as Foundry stores it on a document (actor.img, item.img): relative to the Foundry root, or an absolute URL. Pass it unchanged; do not prefix it with / or run it through foundry.utils.getRoute. icon takes Font Awesome classes from the sheet the running Foundry ships (6 Pro on Foundry 13, 7 Pro on Foundry 14); a class absent from that build draws an empty box. size is required and is 22, 24, 26, 28, 30, 32, 34, 36, 38 or 44, the art ladder. glyph is the ladder’s glyph size for that rung: 10, 10, 11, 11, 12, 13, 14, 14, 15 or 18, in the order of the sizes above. alt is as for Avatar. tint is one of Avatar’s tint keys, and it recolours the glyph alone. variant is '' or glyph-chip. tone is '', success, danger, accent, warning or info, and it outranks tint. ink is '', success, danger, neutral, accent, warning or info, it outranks tint, and it outranks tone on the glyph. A tone paints the edge, ground and glyph in its family’s -border, -soft and -text tokens, as accent does in --fab-accent-border, --fab-accent-soft and --fab-accent-text; an ink inks the glyph alone in its family’s -text token, and neutral in --fab-text-secondary. A variant of glyph-chip draws no edge, so a tone shows its ground and glyph alone. A tone or ink outside its set draws as '', byte-identical to unset. The tone and ink values warning and info are additive at version 1: a Fabricate that predates them draws the tile as unset, and refuses nothing. A tone’s glyph clears the 4.5:1 small-text floor on its own ground over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and not over --fab-bg-3; an ink over a tone’s ground clears it on the same four. An ink on the untoned tile, whose ground is --fab-bg-3 wherever the tile sits, clears the 3:1 non-text floor in every palette and not 4.5:1: success, danger, info, neutral and accent fall under it in hearth-herb, and danger and neutral in ironblood-forge, the weakest danger at 3.50:1. A tone or an ink is colour alone and is not announced, so say the state it marks in text beside the tile. The ink value accent is additive at version 1: a Fabricate that predates it draws the tile as unset, and refuses nothing. text is a string of one to three code points, or a finite number that writes as one to three, and it is unset by default. Each code point is a letter, a number, a punctuation mark or a symbol that draws, so a space, a control or format character such as a zero-width space or joiner, a combining mark, a variation selector, and the blank Hangul, Braille and other default-ignorable code points are outside the set. Code points are counted and not UTF-16 units: 😀 is one, a flag of two regional indicators is two, and an emoji sequence joined by a zero-width joiner or ending in a variation selector is outside the set. A tile with text draws it in the mono face at weight 500 and the rung’s glyph size, centred in the tile, in place of art and icon. text outranks art, and no alt is then drawn. A text that is data but outside its set draws the tile as unset, with art or icon. As for every data key, the seam refuses a function and a value that is not plain data, such as a Date or a class instance, with a TypeError. The component never shortens text, so a four-code-point value draws the art or glyph and a count past 999 is yours to abbreviate. The tile clips what is wider than it, so pass the rung’s glyph with text: the default glyph size of 0.9rem can clip three characters on a small rung. A numeral of up to three digits fits inside every rung at the rung’s glyph size, measured in a monospace face. The text draws in --fab-text on the untoned tile and in the -text token of its tone on a toned one, and tint and ink recolour the glyph alone and never reach it. The text is small text: --fab-text on --fab-bg-3 clears 4.5:1 in every palette, the weakest 4.90:1 in hearth-herb, and a tone’s -text on its own ground clears 4.5:1 over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, the weakest 5.85:1 for danger in hearth-herb. Under a list row’s selected fill, --fab-surface-active, the same holds on every page ground but --fab-bg-2, where danger in hearth-herb reads 4.39:1. The text is hidden from assistive technology, as the glyph is, so a numbered tile carries no name and cannot be named in place, because aria-label and role are not published: always say the number in text beside it, such as Stage 3, which may be visually hidden where a visible duplicate is unwanted. Under forced colours the text draws in the system text colour on a ground of the system canvas colour, so a tone shows in neither. The tile declares no transition or animation, so reduced motion has nothing to change. text is additive at version 1: a Fabricate that predates it refuses it with "text" is not a prop of Medallion, which describe(...).props shows by leaving the key out. The tile’s corner follows its rung: 6 at 22 and 24, 7 from 26 to 32, 9 from 34 to 38 and 11 at 44. The rungs 24, 28, 32, 34, 36 and 44 are additive at version 1: a Fabricate that predates one draws that size at its edge with the corner 9, and refuses nothing. A size off the ladder draws at its edge with the corner 9 and is not published. The glyph is hidden from assistive technology, so a tile without art carries no name: always draw the name as text beside it, and pass alt: '' when you set art. The tile is inline: give its target display: flex, so the tile is a flex item as every Fabricate site draws it.
FillBar
FillBar draws a rounded track with a fill as wide as its value. value is 0–100 and is clamped. tone is success, warning, danger, info, accent or neutral, or a tag name, ember, butter, peach, verdant, mist, azure, lavender, rose, bone or slate, and defaults to success. A tag name paints the --fab-tag-* token of the same name, and it is one of Avatar’s tint keys: sage, aqua and mauve are tint keys too and are not tones. Any other tone draws neutral, a token spelling, a raw colour or a different case included. color is a var(--fab-…) colour token reference, and it overrides tone. shares is an array of { weight, tone? }: two or more draw the fill as abutting shares, each weight over the sum of the weights wide, and the whole stack is value wide. A share’s tone is one of the sixteen tones above, and it defaults to success; a tone outside them draws neutral. A share states its colour by tone alone, so a stack of more than sixteen contributors repeats a tone. A member of a share other than weight and tone is private, and Fabricate drops it from the copy it renders, so a color on a share paints nothing. The shares run left to right in every writing direction and abut with no gap, and no share takes a minimum width, so one narrower than a pixel may not be seen. A weight that is not a finite number above zero reads 0, a numeric string and Infinity included, and shares that all read 0 draw nothing. A null entry reads as {}, and one entry, none or a shares that is not an array draws the one fill from tone and color. Stacked, tone and color are not read and the bar carries no tone attribute. The shares are colour and width alone and are not announced, and neighbouring tones can sit under 3:1 against each other, so state each share as text beside the bar. A Fabricate that predates shares refuses it with "shares" is not a data attribute, and describe('FillBar').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. A Fabricate that predates the tag names refuses nothing and draws each neutral, and describe cannot tell you which one is running, so state each share as text beside the bar on either; adding them is additive, and the entry stays at version 1. Each tag name reads against the bar’s track no weaker than the weakest of the six tones does, in every palette, on --fab-bg-0, --fab-bg-1, --fab-surface, --fab-bg-2 and --fab-surface-soft over --fab-bg-2. That is not 3:1 everywhere, as the shipped tones are not either, so the colour never carries a share alone. Under 3:1 are ember, azure and slate in foundry-native, ember and slate in ironblood-forge and slate in hearth-herb, in foundry-native on --fab-bg-2 as well as on a card, and the rest on a card, so never leave a share to its colour. The bar draws no label, so no ink is paired with a tag name. origin is start or center, and start when absent or any other value. center reads value as -100 to 100, clamped, and grows the fill from the midpoint of the track: to the right in --fab-success-text above zero, to the left in --fab-danger-text below it, and a fill of no width at zero. It runs left to right in every writing direction, as shares do, and tone, color and shares are not read, so the bar carries no tone attribute. A bipolar bar has no midpoint mark, and the success and danger inks are the pale text inks, so state the signed reading as text beside it. A Fabricate that predates origin refuses it with "origin" is not a data attribute, and describe('FillBar').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. neutralBand is a number of zero or more on the same -100 to 100 scale, and 0 when absent; it is read while origin is center alone: a reading no further from zero than it, its edge included, draws in the neutral tone’s ink, --fab-text-subtle, on its own side of the midpoint and as far as it reaches, and a reading beyond it draws in --fab-success-text or --fab-danger-text by its sign. So neutralBand: 20 draws +10, +20 and -20 neutral and +21 and -21 by sign, and zero is neutral, a fill of no width, at any band. A neutralBand that is not a finite number of zero or more reads 0, a numeric string, NaN, Infinity, a negative number and true included, and 0 draws the bar by sign alone, as a bar with no band does; a band of 100 or more draws every reading neutral. The bar announces nothing and its inks never say good or bad: the neutral ink is weaker than the signed ones, under 3:1 against the thin track in hearth-herb, ironblood-forge and starglass-arcana, the weakest 2.1:1 in hearth-herb, and just under 3:1, at 2.96:1 and 2.97:1, against the default track on --fab-bg-2 in ironblood-forge and hearth-herb, where the signed inks clear 3:1 on every track. So state the signed reading and its band as text beside the bar, as “+10, neutral”. Under forced colours a bar whose neutralBand is above 0 draws its fill in the system text colour, solid beyond the band and as a hollow 1px ring within it, so the band is told by shape and the sign by side, never by colour alone. A fill only a few pixels wide has no room for the ring: in Chromium a reading of +2 on a 240px track, a fill about 2.4px wide, paints as a solid 2px mark, where +3, about 3.6px wide, shows its ring, so a reading that close to zero is told from one beyond the band by its width alone, and your text carries the reading. A Fabricate that predates neutralBand refuses it with "neutralBand" is not a data attribute, and describe('FillBar').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. density is default, compact or thin, an 8px, a 6px or a 4px track, and any other value draws default. thin draws no border and paints the track --fab-bg-3 on any ground, so the fill is the whole 4px. Under forced colours the user agent paints every background to the ground, so a fill is drawn solid in the system text colour instead, a single fill, a stack of shares and a centred fill alike, but for a banded bar’s fill within its band, which is a hollow ring. A caller’s color is not drawn there. A thin track keeps a 1px edge in the system text colour, drawn as an outline outside its own box, so its extent and midpoint stay visible and its fill keeps the whole 4px. A parent that clips its overflow clips that outline, so the edge there is the parent’s own. A stack of shares is one solid fill there, so state each share as text beside the bar. A bipolar bar draws no midpoint mark, in any mode: its fill always starts at the midpoint, so the side it grows to tells the sign without colour, and a reading of zero draws an empty track. Under forced colours a bipolar bar differs from a start-origin bar by the text beside it alone, because a reading of -100 draws the same pixels as a start-origin value of 50, so state the signed reading as text. Against --fab-bg-3 twenty of the 112 readings of the sixteen tones in the seven palettes are under 3:1, in foundry-native, hearth-herb, ironblood-forge and starglass-arcana, and none is under 1.8:1, so never leave a reading to its colour. The weakest are danger and slate in hearth-herb, at 1.9:1. A Fabricate that predates thin draws the default track and refuses nothing, and describe cannot tell you which one is running; adding it is additive, and the entry stays at version 1. It is decorative: it has no role and no name and reaches no assistive technology, so state the reading as text beside it. A value that must be announced is a Meter.
Meter
Meter states a value against a maximum to assistive technology, over a FillBar track. value is read against max. max defaults to 100, and a max of zero or less reads full. segments is an array of { value?, tone?, color? }, drawn in order as segments of the one fill; tone and color are each as FillBar’s, and an empty array draws success. Each entry but the last spans its value, a finite number of zero or more on the scale of max, and stops where the fill ends. Any other value reads 0, a numeric string and Infinity included, and a null entry reads as {}. The last entry spans the rest of the fill, and its value is not read. An entry that spans 1e-9 or less on the scale of max is not drawn, so the segments drawn make up the fill. That bound is absolute, so a max of 1e-9 or less reads every entry as nothing. A list that draws one segment or none draws one fill: in that segment’s paint, or in the first entry’s paint when none spans anything, at a reading of 0 or at a max of zero or less, which reads full. A segment’s tone takes the tag names as FillBar’s does, and a name outside the tones draws neutral, as segments: [{ value: 3, tone: 'ember' }, { tone: 'azure' }]. A Fabricate that predates the tag names draws each neutral, and refuses nothing. Meter has no tone key of its own, and "tone" is not a data attribute: for one tone across the whole fill, pass one entry, as segments: [{ tone: 'accent' }]. The segments run left to right in every writing direction and abut with no gap, and only the fill’s two ends are rounded, so two neighbours of one paint read as one segment. No segment takes a minimum width, so one narrower than a pixel or than the fill’s rounded end may not be seen. The segments are colour and width alone, are not announced, and neighbouring tones can sit under 3:1 against each other, so always state each segment as text beside the meter and in valueText; the bar alone never carries the split. Under forced colours the segments draw as one solid fill, as FillBar’s shares do, so the split is told by that text alone. A segments that is not an array (null, an object, a string or a number) is a fault: Fabricate logs it, empties target and the handle goes inert, as for any published component that faults. Drawing a second or later entry and reading an entry’s value are additive, and the entry stays at version 1. A Fabricate that predates segments draws the whole fill in the first entry’s paint and refuses nothing, and describe cannot tell you which one is running, so the text beside the meter carries the segments on either. valueText is the reading, announced in place of the bare number. Pass valueText whenever max is not 100 or the unit matters, because without it only the bare value is announced. label is required and is the meter’s name, drawn visually hidden. It draws no figure, so the visible reading is yours to draw.
BandedBar
BandedBar draws percentages as bars whose whole fill takes one hue from a fixed ramp. rows is required and is { id?, name, percent, fill? }[]. name is required in every row, percent is a whole number 0–100 printed as <percent>%, and every id is unique. One row is a meter named by its name, which is also its visible caption. Several rows are a histogram. An empty rows draws nothing. fill is a FillBar tone, the ten tag names included, or a chance-ramp key, from certain to impossible: guaranteed, common, uncommon, rare, very-rare, legendary and none (the zero-chance step). Absent, the row takes the ramp’s hue at its percent when direction is ascending, and the risk scale’s when it is descending. A tag name paints as FillBar’s does, and a name outside every set draws neutral, as does a Fabricate that predates the tag names. direction is ascending or descending. density is default or compact; at compact a single row draws the histogram’s band row. In a histogram the bars are hidden from assistive technology and each row is read as its name and its percentage; the list carries no name, so head it with your own text.
StatBox
StatBox draws one figure and a micro-label in a bordered box. value is required and is the formatted figure. label is required. icon is optional Font Awesome classes for a glyph. tone is default, info, success or danger, and any other value draws default. info and success ink the figure alone, in --fab-info-text and --fab-success-text, which clear the 4.5:1 small-text floor on the box’s own --fab-bg-1 fill in every palette. layout is default or start, a string, and defaults to default: default draws the centred serif figure over its label, and start draws the label over a start-aligned monospace figure. Any other value draws default. note is optional text, final display text, drawn after the figure and label in either layout, wrapping at the box’s width and never clipped; an empty note draws nothing. In the danger tone the note takes the danger ink and the label the secondary ink, because the muted ink falls under 4.5:1 on the danger fill over --fab-bg-2 in four palettes; ink small text of your own on a danger fill --fab-text-secondary for the same reason. A Fabricate that predates layout or note refuses it with "<key>" is not a data attribute, and describe('StatBox').props shows whether the running one publishes it; adding either is additive, and the entry stays at version 1. The tone success is additive at version 1: a Fabricate that predates it draws the figure in the default ink, and refuses nothing. The glyph is hidden from assistive technology and the tone is colour alone, so label must say what the figure is and what a danger, info or success tone means. A screen reader reads the box’s text in the order it is drawn and adds no name of its own: the figure then the label at default, the label then the figure at start, and the note last in both. So pass a label that makes sense before the figure and after it, and a note that adds to them and never repeats either. The box has no role and the label is not a heading. children is a content slot whose element is a <div>; the box draws the content slot’s children after the figure and label and before the note, in either layout, in a column it spaces, as wide as the box’s content and --fab-space-2 below them. It is for the figure’s own picture, as a published FillBar at density thin, the 4px track of a progress tile: the bar has no role and no name, so a screen reader still reads the box’s text once, the figure and the label in their layout’s order and the note last, and leaves the bar to the figure. A Meter there has a name and a value of its own, so it would announce the figure a second time; never mount one in the slot beside a figure. Content there inherits the box’s alignment, centred at default and from the start at start, and target’s ink, so state the ink of any text you draw there, and on the danger fill ink small text --fab-text-secondary. The box draws nothing focusable and the slot is not a place for a control, because a number a user can change is a Stepper, never a stat box. The box never moves its content slot while it is requested, and an update that changes layout, tone or note keeps the slot in place. A Fabricate that predates children refuses it with "children" is not a data attribute, which describe('StatBox').props shows; adding it is additive, and the entry stays at version 1.
InfoStrip
InfoStrip draws a read-only strip of current values under a kicker. label is required and is the kicker, which names the group. facts is required and is { icon?, label?, value }[]: icon is Font Awesome classes for a decorative glyph hidden from assistive technology, label and value are final display text, and a fact whose meaning rests on its glyph needs a label. A fact takes no other member: props, which the component would spread onto the fact as attributes, is dropped from a copy of every fact on mount and on update and is never written. A data-action, a class, a title or an aria-label there reaches no element, and your own object is unchanged. Put a hook or a tooltip on your own target element, and carry each fact’s meaning in its label and value text. badge is { label, tone } or null, with tone one of positive, warning, danger, info, neutral and accent.
Kicker
Kicker draws the small upper-case label that heads a block, the component the design system calls a kicker. children is required and is the label, final display text; the component draws it in upper case. as is p, span or h3, and defaults to p. An update that changes as replaces the kicker’s root element; the mount, its handle and its claim on target are unchanged. tone is default or accent. size is '', '8' or '9', a string, and defaults to '': '' draws the 8.5px label, and '8' and '9' the 8px and 9px labels, at 0.11em and 0.12em tracking against the default’s 0.11em; what it draws for any other value is private. The 8px label is the smallest type Fabricate draws: keep it to a few words, and never let it alone carry a state or an instruction a user must act on. The size changes the type and never the ink, so the contrast figures below hold at every size. A Fabricate that predates size refuses it with "size" is not a data attribute, and describe('Kicker').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. for is the id of a labelable control you draw, a non-blank string, and has no default: set, it draws the kicker as a <label for> in the kicker’s type, whatever as says, so the caption names the control. Any other value, '', a blank string, a number or true among them, draws the as host with no for, and as is not read while for is a non-blank string. The id is yours: Fabricate draws no id and reads none of its own, so keep your id unique in the document, and a for that matches no labelable control names nothing and throws nothing. A label names an <input> that is not hidden, a <select>, a <textarea>, a <button>, a <meter>, an <output> or a <progress> that you draw, and it cannot point at one of Fabricate’s published controls, which take no id and are named by their own ariaLabel. The label’s text is the control’s accessible name. A click on the caption does what a click on any <label for> does: it focuses a text input, a number input, a textarea or a select, and it activates a checkbox, a radio, a button input or a <button>, which toggles or presses it. So do not point a caption at a control that a stray click on the caption must not fire. A control that carries its own aria-labelledby or aria-label takes that name instead, so keep the visible caption in it: an aria-label contains the caption’s text, which is the label-in-name rule. Drawn as a label it is an inline mark like span, so give its target display: flex. A Fabricate that predates for refuses it with "for" is not a data attribute, so check describe('Kicker').props.for before you pass it, and name the control with aria-labelledby where it is absent. Adding for is additive, and the entry stays at version 1. Its text is its whole name, which Chromium’s accessibility tree states in upper case, as the kicker draws it, whichever host it is, so pass sentence case and never an upper-case literal. h3 makes it a level-3 heading, so pass it only where the kicker heads the content beneath it. It takes no id: to name a control or group with it, put the id on target and point aria-labelledby there. accent is colour alone and says nothing. It clears the 4.5:1 small-text floor on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and not on --fab-bg-3 or a light fill over --fab-bg-2, so draw it on those four grounds. Drawn as span it is an inline mark: give its target display: flex, so the mark is a flex item as every Fabricate site draws it and target is exactly as tall as the mark. Rest data-* is for your own hooks. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element with no role and no focus. For a tooltip pass data-tooltip-text, not data-tooltip, which Foundry localises and otherwise reads as HTML; it opens on pointer hover only, so it never says what the label does not.
Chip
Chip draws a short, fully rounded badge that states a count, a state or a category. children is required and is the chip’s label, final display text, except in the icon-only chip ariaLabel describes. tone is positive, warning, danger, info, neutral or accent; absent, the chip is drawn in the default ink. This is InfoStrip’s badge set. neutral is the recessive tone and clears 4.5:1 on --fab-bg-0, --fab-bg-1 and --fab-surface only. density is default or list; this is the chip’s own set, not FillBar’s. At list the label is one line and is never wrapped or clipped, so a label wider than target overflows the chip: keep a list label short or set truncate. At default a long label wraps inside the chip. emphasis is outlined, bare, solid or dashed; absent, the chip is drawn in its tone’s own fill. It is a second axis beside tone: outlined keeps the tone’s edge and ink on --fab-bg-1, bare draws no edge and a smaller glyph, solid draws an opaque ground for a chip read over artwork, in the tone’s colour where the tone has one, and dashed dashes the tone’s edge, for a locked or provisional chip. dashed is drawn and never announced, and the edge stays dashed under forced colors, so the label or ariaLabel says the state, as a lock glyph beside Locked until the harvest does. On the default tone the dashed edge is --fab-border, 1.46 to 1.78:1 against the four grounds across the palettes, so it is decoration; and struck dashes the edge too, so an icon-only struck chip and an icon-only dashed one look alike. The figures stated for neutral hold for a chip with no emphasis; measure the combination you draw. What the chip draws for a value outside the set is private; today that is the default chip. icon is optional Font Awesome classes for a leading glyph, hidden from assistive technology; absent, no glyph is drawn. The glyph is never the chip’s name, so a chip whose meaning rests on it carries that meaning in its label. ariaLabel is optional final display text, the chip’s accessible name; a blank string or any other value draws no name. Beside a label the label is hidden from assistive technology and ariaLabel is drawn beside it as visually hidden text, so the chip keeps no role and a reader hears the name once, as inline text, with no image role; so never put a control or other interactive content in a named chip’s label. The name must contain the label’s words as one run of whole words, as Button’s ariaLabel must, and a mount or update whose non-blank ariaLabel does not contain children throws "ariaLabel" must contain the text of "children" ("<label>" is not in "<name>"); use it for a short label whose meaning needs more words, as 3 named 3 days waiting. With icon and ariaLabel both non-blank, children may be absent, '' or white space alone, which draws the icon-only chip: the glyph alone on a square, 20px at default and 15px at list, role="img" under ariaLabel with the glyph hidden from assistive technology, and ariaLabel written as its data-tooltip-text, which Foundry shows on pointer hover only; a rest data-tooltip-text you pass replaces that. An empty children with neither key throws Chip requires a non-empty "children", as before, and with one of them throws Chip requires a non-blank "<key>" when "children" is empty, naming the missing icon or ariaLabel; a string of white space alone, or a value that is no string, counts as missing, and a children of white space alone without both keys is refused as an empty one. The icon-only chip is no control: it takes no focus and offers no target, so the 24px pointer-target floor (WCAG 2.2 success criterion 2.5.8) does not apply, and its tooltip opens on pointer hover only, so a keyboard or touch user never sees it: state the state in visible text in the row or detail the chip sits in, never in the glyph and its tooltip alone. Its glyph clears 3:1 against its fill over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 under every published tone and none, in every palette, with no emphasis, dashed or bare, which share that paint, and on the outlined and solid grounds; its tone is colour alone, drawn alike under forced colors: pass a glyph that differs for each state, as a check, a cross and a question mark, and say the state in ariaLabel. In Chromium’s own accessibility tree the icon-only chip is an image named by ariaLabel with nothing beneath it, and a named labelled chip has no image role and holds the name as its one text, the label ignored. Playwright’s accessibility snapshot reads them as img "<name>" and as the name’s text. No screen reader was tested. describe('Chip').props.children stays { kind: 'text', required: true }, and a describe that names ariaLabel is from a Fabricate that draws the icon-only chip and dashed: one that predates them refuses ariaLabel with "ariaLabel" is not a data attribute and an empty children with Chip requires a non-empty "children", and draws dashed as the default chip, so read describe('Chip').props.ariaLabel before you pass any of them; adding them is additive, and the entry stays at version 1. mono is true or false; true sets the label in the monospace face with tabular figures, so columns of counts, DCs and quantities line up. struck is true or false; true draws the label struck through on a dashed-edged chip, for a value switched off in the scope being read, and bare draws no edge. It is drawn and never announced, so the label says the state. truncate is true or false; true keeps the label to one line and ends it in an ellipsis where target is too narrow, at any density, keeping the icon glyph whole. The ellipsis is drawn only: the label stays whole in the chip’s text and so in its name, and the colour, mono, struck and icon are drawn as without it; only the corner changes, to a pill (border-radius: 999px). To let a reader see the clipped text, pass the full label as data-tooltip-text, which opens on pointer hover only, so it never carries what the label does not. The chip ends at the width target has, so a target that is a flex item of your row needs min-width: 0 and a flex-shrink above 0, or the row overflows instead of the label ending in an ellipsis. Fabricate coerces none of mono, struck and truncate to a boolean, so only true and false are in the contract: the string 'false' draws the class. A Fabricate that predates emphasis, icon, mono, struck and truncate refuses each with "<key>" is not a data attribute, and describe('Chip').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. It is a statement, never a control: it takes no focus, and but for the icon-only chip it has no role and its label, or its ariaLabel in the label’s place, is read as inline text. tone is colour alone, so the label says the state. A label changed through update is not announced; a live region is yours to provide. Every other density the component draws, and its lit emphasis, is private. The seam withholds every other tone the component draws, muted and subtle among them, so such a tone draws as none, as an unknown value does; a Fabricate that predates this draws them as its private tones. The chip is an inline mark: give its target display: flex, so the mark is a flex item as every Fabricate site draws it and target is exactly as tall as the mark. Rest data-* is for your own hooks. data-chip-* names are the chip’s own. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element with no role and no focus. For a tooltip pass data-tooltip-text, not data-tooltip, which Foundry localises and otherwise reads as HTML; it opens on pointer hover only, so it never says what the label does not.
Rail
Rail draws one section of an inspector column: an optional kicker over your own content. label is optional final display text, drawn as the section’s kicker in upper case. With it the section is a group named by it; without it, an unnamed <section>, never a landmark. Pass sentence case. children is a content slot whose element is a <div>; the rail draws the content slot’s children in a column it spaces, the first a little further below the label. A child that draws nothing still takes its gap, so remove or hide an empty one. The rail draws no box, fill or padding. It is lazy, so mount('Rail', …) throws "Rail" is not loaded until load(['Rail']) has resolved, as Mounting, updating and destroying describes. The label takes Kicker’s ink, size, weight and tracking, so the same four grounds apply; it inherits target’s face and line height, which a Kicker states for itself. It is not a heading. The rail never moves its content slot while it is requested. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element that takes no focus. For a tooltip pass data-tooltip-text, not data-tooltip, which Foundry localises and otherwise reads as HTML; it opens on pointer hover only, so it never says what the rail’s label and content do not.
InspectorCard
InspectorCard draws the bordered card shell, the design system’s card, around your own content, under an optional head. children is a content slot whose element is a <div>; the card draws the content slot’s children in a column it spaces, inside its own padding, so add neither. Its fill is --fab-bg-2 and it states no ink or type, so your content is on that ground and inherits from target: a Kicker and a Rail label clear 4.5:1 there, and a neutral Chip does not. It is drawn the same in the Manager, the player window, a Fabricate dialog and, under the standalone style root, a companion’s own window or dialog. It is an unnamed <section> with no role; head it with title, or head its content yourself, for example with a Kicker, as h3 where it heads the whole card. title is optional final display text, the card’s title, drawn as a level-3 heading in the serif face at the top of the card, above the content slot’s children; '' or absence draws no head. Pass it only where a level-3 heading fits your outline; where none fits, pass no title and head the card yourself in the content slot. The head is drawn only while title is given, so note, leading and trailing draw nothing without it; a title of white space alone still draws the head, with a blank heading, so pass none instead. note is optional final display text, a line under the title in a smaller ink, which wraps; '' or absence draws none. leading is a content slot whose element is a <span>, drawn before the heading at the top of the head, for its tile: mount a published Medallion there, at size 34 for the design system’s head tile, or an Avatar. On a toned card, give the Medallion the same tone, so the tile is a second cue beside the edge. trailing is a content slot whose element is a <span>, drawn after the heading at the far edge of the head, for controls that act on the whole card, such as a published Button or IconButton. The head spaces each slot’s children by gap and centres them on one line; where the head is too narrow to keep the leading slot and the heading 8rem wide together beside the trailing slot, the trailing slot drops beneath them, still at the far edge, the inline end, and the heading never leaves the leading slot’s side. The trailing slot wraps its own children and never grows past the head’s width, so several controls there wrap among themselves inside the card. The leading slot, the heading and the trailing slot are in that order in the DOM, so a screen reader and the Tab key reach a control you draw in the trailing slot after the title and the note, and before the content slot. The card never moves a head slot while the head is drawn; an update that drops title removes the head with the slots and what you drew in them, which may hold focus, so move focus first, and an update that gives title again draws the same slot elements, with what you drew in them. tone is warning, success, accent or info; absent, or any other value, danger and neutral among them, draws no tone, and nothing is coerced. It draws the card’s edge in the tone’s border colour on the tone’s translucent soft fill, in place of --fab-bg-2, so the card is tinted over whatever ground is behind it; under forced colours, where the reader’s palette repaints every edge alike, a toned card also draws a second 1px edge inset in its padding. Colour is never the only carrier of the state: every tone’s edge falls short of 3:1 against each of --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in at least one palette, so say the state in words, in title, note or your content, as “Over the limit” or “Ready to finish”. The title’s --fab-text ink clears 4.5:1 on every tone’s fill over those four grounds in every palette, and not over --fab-bg-3; the note inks --fab-text-muted on an untoned card and --fab-text-secondary on a toned one, and clears 4.5:1 on the same fills over the same grounds. Your content in the slot keeps target’s ink: --fab-text-muted falls short of 4.5:1 on a toned fill over --fab-bg-1 and --fab-surface in one palette, over --fab-bg-0 in one at every tone but success, and over --fab-bg-2 in five or six, so ink small text you draw in a toned card --fab-text or --fab-text-secondary. A published Button’s keyboard ring clears 3:1 on every tone’s fill over the four grounds. A Fabricate that predates tone, title, note, leading and trailing refuses each with "<key>" is not a data attribute, and describe('InspectorCard').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. Never nest a card in a card: the design system has two container levels, and the second is the published Well, which you mount in the card’s content slot. The card’s padding, gap, corner and border figures, the head’s own figures, and how Fabricate redraws a card inside its own Checks rail and inspectors are private. The card never moves its content slot while it is requested. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element that takes no focus. For a tooltip pass data-tooltip-text, not data-tooltip, which Foundry localises and otherwise reads as HTML; it opens on pointer hover only, so it never says what the content does not.
EmptyState
EmptyState draws the design system’s empty state: a dashed panel that says what is absent and holds the way out. title is optional final display text, the short statement of what is absent, drawn as a level-3 heading. Pass it only where a level-3 heading fits your outline: under a heading for the region the panel sits in, and not inside a card or rail you have yourself headed at level 3. Where no level-3 heading fits, draw your own heading above the panel and pass hint alone. hint is optional final display text, the sentence beneath the title. Pass a title, a hint or both; with neither the panel is an empty box. icon is optional Font Awesome classes for a glyph tile above the title, hidden from assistive technology; absent, no tile is drawn. compact is true or false: true draws a smaller glyph tile and tighter padding, for a sidebar or a popover. inline is true or false: true draws the panel as one line, a row whose glyph is released from its tile and sits beside the sentence, for a line directly above a control. note is true or false: true releases the panel itself, with no dashed edge, corner, fill or tile, as one quiet line at a popover’s own type scale reading from the left, for the inside of a popover you have drawn. Where more than one is true, inline overrides what compact sets and note overrides what inline sets, and what the later does not set stands: with inline and note the panel is released and its stack stays a row. Each composes with filtered, which adds the muted ink. The content slot’s children sit beside the hint under inline, and read from the left under note, so they are not centred there. Fabricate coerces none of compact, inline and note to a boolean, so only true and false are in the contract: the string 'false' draws the class. A Fabricate that predates compact, inline and note refuses each with "<key>" is not a data attribute, and describe('EmptyState').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. filtered is true or false: true draws the plain panel, in the muted ink, with no tile or title, for filters that match nothing, which is not an absence of content, so pass hint alone with it. The hint is plain text, so a search term in it takes no emphasis. children is a content slot whose element is a <div>; the panel draws the content slot’s children under the hint, in the column it spaces. It is the way out of the dead end, a control or a link; what is drawn there is your own, and a control you draw there is named by you. Content there inherits the panel’s quiet ink and its alignment, centred or from the left under inline and note, not target’s, so state the ink of any text you draw there. It has no role and no name and is not a live region: when a list empties in answer to an action, the announcement is yours. It draws no fill, so it sits on target’s ground. The title inks --fab-text, which clears the 4.5:1 small-text floor on --fab-bg-0, --fab-bg-1, --fab-surface, --fab-bg-2, --fab-surface-soft over --fab-bg-2 and --fab-bg-3 in every palette. The hint inks --fab-text-muted on every variant, which clears the 4.5:1 small-text floor on --fab-bg-0, --fab-bg-1, --fab-surface, --fab-bg-2 and --fab-surface-soft over --fab-bg-2 in every palette. The title states its own serif face, and the hint inherits target’s. Under note the title drops the serif face and inks --fab-text-muted as the hint does, which clears the same floor on the same grounds, since note draws no fill. The panel’s own figures are private. The panel never moves its content slot while it is requested. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element that takes no focus. On a component that holds a content slot it also catches every click on what you draw there, since the window takes the nearest data-action above the click. For a tooltip pass data-tooltip-text, not data-tooltip or data-tooltip-html, which Foundry reads as HTML; it opens on pointer hover only, so it never says what the panel’s text and content do not. data-tooltip-class and data-tooltip-direction on it apply to every tooltip inside its content slot.
Notice
Notice draws the design system’s notice: what just happened or is wrong right now, which goes away. It is not a standing statement: a rule that is always true is not a notice. It is not a Foundry notification: it is drawn in your element, and ui.notifications knows nothing of it. title is required and is the sentence that names what happened, final display text. detail is optional final display text, a second line that says what to do next. tone is danger, warning, info, success or accent, and defaults to danger; any other value draws danger. It repaints the edge, the fill, the glyph and the title; the glyph is hidden from assistive technology, danger and warning share one and info and accent share another, so the title says the state. accent was the notice’s own tone before it was published, so a Fabricate that predates its publication draws it too; it is additive at version 1. icon is optional Font Awesome classes for the leading glyph, which is hidden from assistive technology; absent, the tone’s own glyph is drawn. action is optional and is { label }, drawing one button after the text; label is the button’s whole accessible name, final display text. An action with no non-blank string label, or with no function to call (onAction, or its own onClick in a Fabricate caller), draws no button. Pass no other member: one this line does not state is private, and a function in it throws "action" must not hold a function. onAction is an optional callback, called with no argument each time the action button is pressed. The label is one line, never wrapped or clipped: where the notice is too narrow to hold it beside the text the button drops beneath, and a label wider than target overflows the notice, so keep it short. The button is drawn the same at every tone and takes no tone of its own, so a destructive action says so in label. danger reports what is wrong and stops the reader’s work; a notice that offers a retry or a resume passes warning. The button has no disabled and no busy state at version 1, and onAction is called on every press, a held Enter key included. Ignore a press you are still handling and, where the wait is perceptible, say so with an update to label. Where several notices are shown at once, each label says what its action acts on, because the label is the button’s whole name and nothing describes it. It is a live region, role="status" with aria-live="polite": a change to its text is announced, and most screen readers also announce one mounted with its text, though some do not, so a notice the reader must not miss also says it in title. An update that changes none of its text announces nothing. Mount it when the thing happens and destroy it when it no longer holds, never as standing text. Every mount is a new announcement, so when your content is drawn again with nothing new to report (a navigation provider’s mount called again, a DialogV2 or Handlebars re-render), keep the notice through update where its target survives and do not mount an unchanged one again. It moves no focus, and takes none except on its action button and its dismiss control; where the act that caused it also moves focus, move focus first and mount the notice after, because a focus change cancels polite speech. Several may be shown at once, stacked; Fabricate arbitrates nothing between them, and only an assertive notice interrupts. Foundry announces nothing of its own, so nothing else speaks for a notice, and one in a minimised window or behind a modal dialog is not announced. assertive is true or false and defaults to false: true at the danger tone, the default and what a tone outside the set draws, draws the notice as role="alert" with no aria-live of its own, for a fault that stops the reader’s work, such as a region of yours that could not be drawn. It has no effect at any other tone, and only the boolean true counts: 'true', 1 and every other value draw the polite status, and none is refused. Never pass it for a routine message, a confirmation or a warning the reader can work around: an alert interrupts whatever the screen reader is saying, and a page that raises alerts for routine news teaches the reader to ignore them. The role is read once, when the notice is mounted: an update that changes assertive or tone repaints the notice and keeps the role it was mounted with, because a role changed on an element already in the page is announced unreliably; to change whether a notice interrupts, destroy it and mount a new one, which is a new announcement. Fabricate inserts an alert already holding its text, in one change to the page, and most screen readers announce an element that appears with role="alert" at once, interrupting what they are reading; whether and how each does is the screen reader’s, so also say the fault where the reader will look for it. While it stays mounted, an update that changes its text is expected to be announced as an alert too, and an alert is read whole, so most screen readers are expected to read the whole notice again, its action’s label included, on any change to its text: change its text only when the fault itself changes. Never show two assertive notices at once: Fabricate arbitrates nothing between them, and a second alert interrupts the first, so where a second fault arrives, update the one you have or destroy it before you mount the next. A Fabricate that predates assertive refuses it with "assertive" is not a data attribute, and describe('Notice').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. Fabricate removes no notice on a timer, so if you do, give a notice that carries an action no time limit. The button’s label is part of the live region: an update that changes it is announced, by some screen readers together with the whole notice, so change it only to report a change of state. An update that keeps action and onAction keeps the same button, so focus stays on it. An update that omits action or onAction, and destroy, remove a button that may hold focus, so where it does, move focus first, as Ownership and theme states. The action button is the first button inside target and the dismiss control the last, so target.querySelector('button') reaches the action and the last of target.querySelectorAll('button') the dismissal. Reach them by that order and not by a data-notice-* name, which is the notice’s own and private. In a host that replaces its content on render (DialogV2, a Handlebars part) the action button is a new element after every render: note in _preRender whether focus was inside target and, after mounting again in _onRender, focus the action button. The keyboard ring is the accent, 2px outside each button and inside the notice’s own padding, and clears 3:1 against the notice’s fill on the four grounds the label clears. dismissable is optional, true or false, and draws a dismiss control after the action. dismissLabel is required while dismissable is truthy; it names the control and says what is dismissed, and is never white space alone. onDismiss is required while dismissable is truthy, and is called with no argument, once, when the control is pressed by pointer, Enter or Space, while it still holds focus. Escape dismisses nothing. The control’s face is the xmark glyph alone; no tooltip shows its name. Dismissal is final for the mount. In onDismiss, move focus to the destination Ownership and theme orders, starting at the next control, since the press leads nowhere, and then call destroy. Where no sensible next control exists, focus target’s container or the control that opened the notice. Removing the focused dismiss button drops focus to body, where Foundry’s Escape closes every open window, so move focus to a control before onDismiss returns. An update after dismissal is validated, returns true and draws nothing. Until destroy, target still holds the mount, so a mount into it throws target already holds a published component. A notice is shown again only by a new mount, which is a new announcement. An update that clears dismissable removes a control that may hold focus, so move focus first. The title clears the 4.5:1 small-text floor at every tone on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and not on --fab-bg-3. The detail is the muted ink over the tone’s fill, and clears that floor in every palette only at danger, on --fab-bg-0, --fab-bg-1 and --fab-surface. At warning, info, success and accent the detail falls short of it on --fab-bg-1, a Fabricate window’s own ground, in up to four of the seven palettes, the default among them; at every tone it falls short on --fab-bg-2, so inside an InspectorCard, and on --fab-bg-3. So say in title whatever the reader must not miss. The action button’s label clears the 4.5:1 small-text floor at every tone, at rest and under the pointer, on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and not on --fab-bg-3 or on a tinted fill over any of them, so never mount a notice with an action inside a tinted panel of your own. Its tile is under 3:1 against the notice’s fill in every palette, so the label alone marks it as a control: pass a verb phrase. The dismiss glyph clears 3:1 against its tile at every tone, at rest and under the pointer, on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and not on --fab-bg-3. It inherits target’s face, and outside the Manager its button takes Foundry’s own button face. The notice’s own figures are private. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. data-notice-* names are the notice’s own: a value you pass under one overwrites what the notice writes. Do not pass data-action: the window dispatches every click inside the notice to it (close closes the window), each press of its action button among them. For a tooltip pass data-tooltip-text, not data-tooltip or data-tooltip-html, which Foundry reads as HTML; it opens on pointer hover only, so it never says what the title, the detail and the action’s label do not. It stays open while the pointer is over the action button.
A worked action follows: the bar that holds a stage after a failed check, drawn on its card’s own ground and never inside a tinted panel. It assumes a target that outlives your re-renders, as a navigation provider’s does; in a DialogV2 or a Handlebars part follow the _preRender and _onRender line above.
// After `load(['Notice'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the callback refuses `action` and `onAction`: draw your own bar there.
if (fabUi?.describe?.('Notice')?.props.onAction?.kind !== 'callback') return;
const held = { tone: 'warning', title: 'This stage is held by the failed check.' };
let allowing = false;
function onAction() {
if (allowing) return; // A second press, or a held Enter key, while the write is under way.
allowing = true;
notice.update({ ...held, action: { label: 'Allowing another attempt…' }, onAction });
// Your own world write; where it fails, set `allowing` back and `update` the first label again.
allowAnotherAttempt();
}
const notice = fabUi.mount('Notice', {
target,
props: { ...held, action: { label: 'Allow another attempt' }, onAction },
});
// Later, when the hold has cleared and you have drawn the roll control it gives way to:
// Move focus only where the button holds it: the write that clears the hold reaches every client.
if (target.contains(target.ownerDocument.activeElement)) rollControl.focus();
notice.destroy(); // Fabricate moves no focus.
A worked dismissal follows: a notice the reader may close, which hands focus to your own next control.
// After `load(['Notice'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the dismissal refuses these props: draw no dismiss control there.
const dismissing = fabUi.describe('Notice').props.onDismiss?.kind === 'callback';
const saved = fabUi.mount('Notice', {
target,
props: {
tone: 'success',
title: 'The recipe is saved.',
...(dismissing && {
dismissable: true,
dismissLabel: 'Dismiss the saved-recipe notice',
onDismiss() {
nextControl.focus(); // The press leads nowhere, so focus moves on before the notice goes.
saved.destroy();
},
}),
},
});
Button
Button draws the design system’s button: a labelled native <button> that is pressed to do one thing. children is required and is the label, final display text, and the button’s accessible name unless ariaLabel replaces it. The button hugs its label on one line while it has the room. Where it is narrower than the label, the label wraps at its spaces inside the button, is never clipped or ellipsised, and the button does not grow taller, so a label that wraps onto more lines than the button holds spills past its top and bottom edges: pass a short verb phrase and give the button the room for one line. A label of white space alone names nothing, so mount and update refuse it as an empty one, with Button requires a non-empty "children", even beside an ariaLabel, so the ariaLabel is never the only name a label-less button has. icon is optional Font Awesome classes for a glyph drawn before the label, hidden from assistive technology; absent, no glyph is drawn. The glyph never joins or replaces the name: a glyph-only button is IconButton. ariaLabel is optional final display text that replaces the label as the button’s accessible name, for a label too short to say its verb, as a visible “+7” named “Credit +7 days to Mira”. A screen reader announces ariaLabel in place of the label, which is still drawn. ariaLabel must contain the label’s words as one run of whole words, so a speech-input user who says the words they see presses the button (WCAG 2.2 success criterion 2.5.3). Fabricate compares the two after NFKC normalisation and case folding, reads each as its words and symbols in order, splitting words with Intl.Segmenter so a word inside unspaced text stands alone, and drops punctuation and spacing, so “Save…” is in “Save the recipe”, “Craft (3)” in “Craft 3 recipes” and “保存” in “レシピを保存”. A symbol is never read as a word and a word never matches part of another, so “+7” is in “Credit +7 days to Mira” and not in “Credit seven days to Mira”, “Credit 7 days to Mira” or “Credit +70 days to Mira”, and “Edit” is not in “Credit the tier”. Where the runtime has no Intl.Segmenter, Fabricate splits words at spacing alone, so a label inside unspaced text is refused there. A mount or update whose non-blank ariaLabel does not contain it throws "ariaLabel" must contain the text of "children" ("<label>" is not in "<name>"), and an update leaves the earlier props drawn, so pass a matching ariaLabel in the update that changes children. Build ariaLabel by inserting the label string itself, as format('… {label} …', { label: children }) with a format of your own, so it contains the label by construction, and put the label first where the language allows, because a translation that rewords or reorders the label’s words makes mount throw M22. An ariaLabel that is not a string, or is blank, writes no name and is compared with nothing, so the label stays the name; the seam drops it from the props, so the component never draws it, and the check is the seam’s. tooltip is optional final display text, a hint the label does not say, as “Rewinds the clock by one day”; a tooltip that is not a string, or is blank, writes none. Fabricate writes it as data-tooltip-text on the button, so Foundry’s own hover listener shows it as plain text, never read as HTML, after a delay while the pointer rests on the button. Under keyboard focus, and only under :focus-visible, Fabricate opens the same tooltip itself through game.tooltip, which it reads when the focus arrives, and closes it on blur, a press, Escape, destroy and an update that changes tooltip or passes disabled: true, as the IconButton section states; it closes only its own tooltip and does not stop Escape, which still bubbles to a keydown listener of yours above target, and whether Foundry’s dismiss keybinding then also runs is not measured. While it is open Foundry sets aria-describedby to tooltip on the button, so a screen reader may read the hint as the button’s description, and if you also pass aria-describedby and no description, restore it as Ownership and theme states. A button whose rest props include data-locked writes and opens no tooltip, because Foundry pins a copy of any tooltip it opens on such an element and the closes above never reach that copy. description is optional final display text, the button’s accessible description, a hint the label does not say, as “Moves the date back 1 day. Credits stay”, which a screen reader may read after the name as its own settings decide. A description that is not a string, or is blank, writes none, and nothing is coerced. Fabricate draws it inside the button as an element hidden from every user, so it is never drawn, never joins the name and moves nothing, and names that element in the button’s aria-describedby, after any ids you pass in aria-describedby. description is the hint a screen reader is given and tooltip the one a sighted user is shown, but while a tooltip is open Foundry describes the button by it too, so give the two different words, because a screen reader may then read both. While description is drawn and a tooltip Foundry opened on the button is open, whichever way it opened, Fabricate writes the button’s aria-describedby as tooltip followed by your ids and the description’s, so a screen reader is given the tooltip and then the description under keyboard focus too, and once the tooltip has closed Fabricate writes back your ids and the description’s, so you restore nothing then. A disabled or busy button keeps its description; a keyboard user never reaches a disabled one, so its description never says why it is unavailable. pressed is true, false or absent, and makes the button a toggle: Fabricate writes aria-pressed with that value, so a screen reader announces a toggle button that is pressed or not pressed, and absence writes no attribute, so the button is no toggle. true draws the pressed face whatever the visual role, at rest and under the pointer: a solid accent tile, its label in the ink drawn on the accent. The pressed face differs from the keyboard ring by more than an outline, being a filled tile where the ring is an outline 2px clear of the button; against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette its label clears 4.5:1, its edge 3:1, and its fill 3:1 against the unpressed face of every role but primary, whose success fill it matches in lightness, so a pressed primary differs by hue alone. Beside disabled the button keeps the pressed tile under the disabled face’s dimming, so a disabled toggle still shows its state, and under forced colours the pressed face is drawn in the reader’s Highlight behind HighlightText, and in GrayText while disabled, so it stays distinct from a button that is not pressed. A toggle is neutral or ghost: with any other role the pressed face replaces that role’s own face, so its verb colour is lost. Fabricate coerces nothing, so a value other than true or false, the string 'true' among them, writes no aria-pressed and draws no face. The button changes nothing itself: a press reports through onclick, and the button shows the new state when your update passes it. The label is the same in both states, because the attribute says which holds, and names what is shown while it is pressed, as “Show the reward”, never “Hide the reward”. A button whose press shows and hides a region is a disclosure, so it passes aria-expanded and not pressed. size is '', '24', '26', '28' or '38', a string, and defaults to '': '' draws the default rung, and '24', '26', '28' and '38' the 24px, 26px, 28px and 38px rungs of the design system’s height scale; what it draws for any other value, a number included, is private. Every rung is at least 24px tall, so the button is its own 24 by 24 pointer target (WCAG 2.2 success criterion 2.5.8); a height between two rungs, as 27px, is no rung, so pass the nearer one, '26'. onclick is a required callback, called with no argument each time the button is pressed, each repeat of a held Enter key included. The key is spelt onclick, all lower case, unlike Notice’s onAction. role is neutral, primary, ghost, dashed, danger, warning, info, accent, urgent or confirm, and defaults to neutral. It is the button’s visual role and sets no ARIA role: the button is a native <button> whatever role says. Each value names a verb, never a colour: neutral is the secondary verb. primary the leading verb of its cluster, at most one in a cluster. ghost the quiet verb that changes no record, never its cluster’s leading verb. dashed the verb that adds to the list it closes. danger the destructive verb. warning the caution verb, which proceeds against a flagged rule or breaks a reference that can be re-made exactly, and destroys nothing. info the verb that reads, rolls or reveals and writes no record, as a roll. accent the forward verb, which moves the work on to its next step, as “Advance”. And urgent the one verb in its cluster that is due now, as that “Advance” once the stage it ends is complete, at most one in a cluster. confirm is the confirming verb, which moves the work a step on without finishing the record, as “Confirm the stage” beside its screen’s primary “Save”, and is never the screen’s commit. A verb that both destroys and cautions is danger. A dashed label starts with its verb, as “Add tier”, because no plus glyph is drawn. accent is outlined: no fill, its label in --fab-accent-text inside a --fab-accent edge, filled in --fab-accent-soft under the pointer. urgent is the solid accent tile, its label in --fab-on-accent, deepening to --fab-accent-hover under the pointer: at rest and under the pointer those are the pressed face’s colours, so a view never shows an urgent button and a pressed toggle together. Under forced colours an urgent button is repainted as a plain button, as an accent one is, and the keyboard ring of a focused urgent or pressed button is drawn in the reader’s CanvasText. Either role is colour alone, so an urgent button always passes icon, a glyph that marks the work as due, and a label that says what is due, because the glyph is hidden from assistive technology; passing urgent in place of accent once the work is due changes only the face. confirm is outlined in the success family: no fill, its label in --fab-success-text inside a --fab-success-strong edge, filled in --fab-success-soft under the pointer, so it never reads as the solid primary it stands beside. The hover fill is a subtle cue, as faint as 1.12:1 against the ground it hovers on, and not the affordance, which is the edge and the glyph. confirm is told from neutral by an opaque edge and, where the palette allows, a green hue, so a confirm button passes icon, a glyph that marks the confirmation, as fas fa-check, and a label that says what it confirms, because the glyph is hidden from assistive technology. Under forced colours a confirm button is repainted as a plain button, as an accent one is, so its glyph and label carry it there. Its keyboard ring is the accent outline 2px clear of its edge, told from the edge by the strip of ground between them and not by colour, because in mythwright the accent and --fab-success-strong are one colour. A row of outlined card actions takes neutral for a plain verb that writes a record, ghost for a quiet verb that changes none, warning for its caution verb, primary for the verb that finishes the record, accent for its forward verb and urgent for that verb once it is due; primary and urgent are both solid tiles, so they never stand in one cluster. An action bar takes primary for its one commit and confirm for a confirming step beside it, and confirm never stands in for primary. A bar never carries confirm and accent together, because in mythwright their edges are one colour. A dialog’s Confirm button that finishes the record is primary, not confirm. A Fabricate that predates the accent and urgent roles draws neutral for each and refuses nothing, which describe cannot show; adding them is additive, and the entry stays at version 1. A Fabricate that predates the confirm role draws neutral for it and refuses nothing, which describe cannot show; adding it is additive, and the entry stays at version 1. A visual role is drawn and never announced: it reaches no assistive technology, so the label says the verb. Confirm a destructive press yourself, in a dialog of Foundry’s, before anything is written; Fabricate’s arm-then-confirm state is private. fullWidth is true or false. Give target display: flex, as for an inline mark: the button then hugs its label, and true spans target. In a block target a dashed button hugs its label too, as every native button does, so only fullWidth: true spans target. disabled is true or false. true draws the button as unavailable whatever the visual role, takes the button out of the tab order and stops every press, so onclick is not called. It is for a verb that cannot apply and whose reason the surrounding text already gives: a keyboard or screen-reader user tabs past a disabled button and is shown no tooltip, so nothing at the button can say why. A verb the user is refused for a reason stays enabled, and its press answers with the reason, in a Notice or a notification of your own. The unavailable label is not held to the contrast floor. Never pass true while the button holds focus, an update made inside onclick included, so a press that starts work passes busy, which leaves the button enabled. busy is true or false. true marks an action in flight: the button keeps its place in the tab order and its focus, takes aria-busy="true" and aria-disabled="true" and never disabled, is drawn dimmed under the progress cursor, and a press, a held Enter key’s repeats among them, calls neither onclick nor a submit. busy beside disabled draws the disabled face. The busy label is not held to the contrast floor. The button draws no busy label, so pass children that say what is in flight where the wait is perceptible, because the control otherwise reads as idle while it refuses. A change to a focused button’s label is not reliably announced, so announce the outcome yourself, with a Notice or a live region of your own. When the work ends pass busy: false and the first label again, or move focus and then remove the button. Fabricate coerces none of fullWidth, disabled and busy to a boolean, so only true and false are in the contract: the string 'false' spans target, disables the button and marks it busy. type is button, submit or reset, and defaults to button; a value outside the set draws button, never the browser’s own default of submit. A submit button submits the <form> that holds target once onclick has returned, so mount it inside a form of your own and handle that form’s submit event; onclick takes no argument, so it cannot cancel the submit, and you cancel it in the submit event. As the form’s first submit button it is also pressed by implicit submission, so Enter in a text field of that form calls onclick and then submits it, and while busy that Enter submits nothing. A reset button resets that form. A form submit in Foundry closes a DialogV2 and saves an editable document sheet, so mount a submit button only in a form you own. A Fabricate that predates size, icon, busy and type refuses each with "<key>" is not a data attribute, and describe('Button').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. A Fabricate that predates the '24' and '26' rungs draws the default rung for each and refuses nothing, which describe cannot show; adding them is additive, and the entry stays at version 1. A Fabricate that predates ariaLabel, tooltip and pressed refuses each with "<key>" is not a data attribute, which describe('Button').props shows by leaving it out, and one that predates the info role draws neutral and refuses nothing; adding them is additive, and the entry stays at version 1. A Fabricate that predates description refuses it with "description" is not a data attribute, which describe('Button').props shows by leaving it out; adding it is additive, and the entry stays at version 1. It is drawn the same in the Manager, the player window and, under the standalone style root, a companion’s own window or dialog. It inherits target’s face; its size, weight and ink are its own. Align your own content to the button by centring, never by restating its height. Your own window or dialog carries no Fabricate root, so the button is drawn there under the standalone style root, and a dialog you open still draws Foundry’s own buttons. Without type: 'submit' it is never a form’s submit button: to submit a <form> of your own from a press, call that form’s requestSubmit() in onclick. Two buttons side by side are two mounts in two targets, which you lay out as a wrapping row --fab-space-2 apart. A target is never Foundry’s .form-footer, which resizes a button that is its child. The button is the only focusable element Fabricate draws in target, inside the standalone style root in a target with no Fabricate root, so target.querySelector('button') reaches it. An update keeps the same button, so focus stays on it; destroy removes it, so where it holds focus, move focus first, as Ownership and theme states. In a host that replaces its content on render the button is a new element after every render, as Notice’s is. The keyboard ring is the accent, 2px wide and 2px clear of the button, so it reaches 4px beyond the button on every side. Leave that much inside any edge of your own that clips, a scrolling container’s among them, and inset a fullWidth button’s target by as much. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and not against --fab-bg-3. The label of an enabled button clears the 4.5:1 small-text floor at rest in every visual role, on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and under the pointer in every visual role but primary, which falls short of it there in the foundry-native palette. ghost and dashed draw no fill, so their label is the muted ink on your target’s own ground and clears that floor by the least. On --fab-bg-3 every visual role but primary and urgent falls short of it in at least one palette. A tinted fill is --fab-info-soft, --fab-accent-soft, --fab-success-soft, --fab-warning-soft or --fab-danger-soft over one of the four grounds, as a tinted card of your own draws it, and each role is measured on all five over all four in every palette. There the label clears 4.5:1 at rest and under the pointer in neutral, warning, info, accent, urgent and confirm, the weakest confirm’s at 4.71:1 under the pointer. primary’s label clears it there at rest and, as on the grounds, not under the pointer in foundry-native; danger’s clears it at rest, and under the pointer on all but --fab-success-soft and --fab-warning-soft over --fab-bg-2 in hearth-herb. ghost and dashed clear it there only under the pointer, because their resting label, the muted ink, falls short on each tinted fill in at least one palette. On a tinted fill the urgent tile and edge clear 3:1, the weakest at 3.67:1, as the accent edge does, and the confirm edge clears 3:1 on all but --fab-accent-soft over --fab-bg-2 in foundry-native, at 2.96:1. For every other role, accent, urgent and confirm excluded, on each of the five tinted fills there is at least one palette and ground where, at rest, both its edge and its tile fall under 3:1, so its label alone marks the button as a control there. accent is excluded because its edge passes on every tinted fill, though its tile is 1.00:1, as it draws no fill. Mount a button on one of the four grounds or on a tinted fill over one of them, never on --fab-bg-3, and never mount a ghost or dashed button on a tinted fill. urgent says its work is due now, never that its verb leads the card, so a forward verb on a tinted card whose work is not yet due takes the outlined accent; Fabricate publishes no other solid forward verb. neutral, ghost, dashed and danger draw an edge under 3:1 against the ground in every palette, so the label alone marks the button as a control: pass a verb phrase. info draws one under 3:1 in six of the seven palettes, and its label, --fab-info-text on --fab-info-soft, clears 4.5:1 on the four grounds at rest and under the pointer, as the pressed face’s label, --fab-on-accent on --fab-accent, does. accent draws its edge in --fab-accent, which clears 3:1 on the four grounds in every palette, and its label clears 4.5:1 on the four grounds and on a tinted fill over any of them, at rest and under the pointer; urgent draws the pressed face’s tile, which clears 3:1 on the four grounds, and the pressed face’s label. confirm draws its edge in --fab-success-strong, which clears 3:1 on the four grounds in every palette, the weakest at 3.94:1 on --fab-bg-2 in foundry-native, and its label clears 4.5:1 on the four grounds at rest and under the pointer; --fab-success itself falls under 4.5:1 as a label in foundry-native and under 3:1 as an edge on --fab-bg-2 there, which is why the role draws the success text and strong rungs. What the button draws for a role value outside its set is private. So are its height, corner, padding, type size and weight. Each visual role’s colours and edge beyond what this section states, among them the success family that primary is drawn in. And how Fabricate redraws a button inside its own toolbars, rows and inspectors. aria-expanded is true or false, and is an aria prop: Fabricate writes it on the button. It is for a button whose press shows and hides a region you draw: pass false while the region is hidden and true while it is shown, in the same onclick that shows or hides it, and omit the prop on a button that does no such thing. Hide the region from assistive technology too, with hidden and not by height alone, because a region hidden by height alone is still read, and pass true only while the region is shown. The label is the same in both states, because the attribute says which holds. Draw the region directly after the button in reading order, so the person who hears “expanded” reaches it with the next move. Focus stays on the button when the region opens or closes, and before you hide a region that holds focus, move focus to the button, because that focus otherwise falls to the page and the next Escape runs Foundry’s dismiss keybinding, which asks Foundry’s windows to close. In Foundry 13 and 14 Foundry reads the attribute nowhere and gives the region no keyboard handling. While the button holds focus Escape reaches no Foundry keybinding, though a dialog still closes on it, as Ownership and theme states; in Foundry 13 and 14, with focus in the region on an element of yours that Foundry does not count as taking keys (a link, a button outside a form, a tabindex container), Escape runs Foundry’s dismiss, which, when no drag, menu, context menu or Tour is open, asks every Foundry window to close. The button draws no chevron and opens nothing itself. aria-describedby is an aria prop: Fabricate writes it on the button. It is the id of one element of your own, or several ids separated by spaces, holding a hint that is visible text beside the button and that adds to the label without repeating it. Each id must exist in the tree that holds target while the button is shown, and the element it names, which may sit beside target and need not be inside it, must not be hidden, which would still be read to a screen-reader user though a sighted user never sees it; an id that does not exist is skipped and the others are still read. The hint is then read to a screen-reader user who tabs to the button, before any description, and the button’s name is still its label alone. The reason a disabled button is unavailable does not go in its hint, because a keyboard user never reaches a disabled button: keep the button enabled and answer the press with the reason, or state the reason in the surrounding text. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. They land on the button itself, so data-keyboard-focus, data-action, data-cursor, every data-tooltip name, and the two names Fabricate’s own stylesheet reads off its own buttons, data-validation-focused and data-essence-sort-direction, are refused with "<key>" is reserved on Button. That includes data-tooltip-text, which the sections above advise for a component whose rest lands on a root that is no control: a button opens no tooltip but its tooltip. The button keeps its own cursor too, so put a hint in tooltip, which keyboard focus opens too, or in text beside the button. Tie a hint in text beside the button to it with aria-describedby. Give the hint element a stable id of your own, for example <p id="acme-notes-hint">, and pass 'aria-describedby': 'acme-notes-hint' beside children, in the props you give mount and each update.
A worked way out follows: an empty panel that holds the one verb that fills it. The panel sits in a target of yours, and the button is judged from the panel’s mount, so it is drawn under a standalone style root where that target has no Fabricate root and under none inside a Fabricate window.
// After `load(['EmptyState', 'Button'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `Button` describes none: draw your own way out there.
if (!fabUi?.describe?.('Button')) return;
const panel = fabUi.mount('EmptyState', {
target, // Any element of yours.
props: { title: 'No projects yet', hint: 'Create one to start tracking.', children: true },
});
const wayOut = target.ownerDocument.createElement('div');
wayOut.style.display = 'flex'; // The button hugs its label, and the panel centres it.
panel.slot('children').append(wayOut); // Append first: the button's root is judged from here.
fabUi.mount('Button', {
target: wayOut,
props: { role: 'primary', children: 'New project', onclick: () => openProjectForm() },
});
panel.destroy(); // Ends the button, then the panel.
A disclosure follows: a button that shows and hides a region of your own, and says which through aria-expanded.
// After `load(['Button'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the prop refuses it: draw your own control there.
if (fabUi?.describe?.('Button')?.props['aria-expanded']?.kind !== 'aria') return;
// A region you drew beside `target`, in the same Fabricate window.
const region = target.ownerDocument.getElementById('acme-project-notes');
region.hidden = true;
let open = false;
const props = () => ({
children: 'Project notes', // The same label in both states.
'aria-expanded': open,
onclick: () => {
open = !open;
region.hidden = !open; // Hidden from assistive technology too.
disclosure.update(props()); // The same props, and the new `aria-expanded`.
},
});
const disclosure = fabUi.mount('Button', { target, props: props() });
StatusToggle
StatusToggle draws the design system’s switch as its button host: a native <button> holding a track and a knob, for a setting that is on or off. By default it exposes the state with aria-pressed and states no role, so it is a toggle button to assistive technology; semantics makes it a switch. The only text it draws is label, beside the track inside the button. A choice between two named things is not a switch: draw your own control for it. on is true or false, and is required: true draws the knob at the far end of an accent track, and false at the near end of a quiet one. Fabricate coerces nothing, so only true and false are in the contract. The button changes nothing itself: a press reports through onclick, and the switch shows the new state when your update passes it, which may be after the press returns. The switch shows no pending state, so if your change takes time, say so in text of your own, and treat a press that arrives before your update as another press from the state you last passed. To refuse the change, pass on unchanged and say why in text of your own, so the switch never shows a state you do not hold. onclick is a required callback, called with no argument each time the switch is pressed, each repeat of a held Enter key included. semantics is pressed or switch, and defaults to pressed: pressed exposes the state with aria-pressed and states no role, and switch states role="switch" and exposes it with aria-checked; a value outside the set draws pressed. Pass pressed for a staged edit that your own Save applies, and switch for a press that writes the setting at once. Fabricate writes aria-pressed, aria-checked and role from semantics and on alone, so none of them is an aria prop or a rest key, and an older Fabricate refuses semantics with "semantics" is not a data attribute, which describe('StatusToggle').props shows. label is optional final display text, the setting’s name, which the switch draws beside its track inside its own button, so a press on its words is a press on the switch. The button is named by label, the text it draws beside its track, or, where you pass it, by ariaLabel, which must then hold that text. Pass label, ariaLabel or both: without either, mount refuses with StatusToggle requires a non-empty "label". A label that is not a string is refused with "label" must be a string. A label of white space alone counts as absent, so it is refused where no non-blank ariaLabel is passed. And a blank label beside a non-blank ariaLabel draws nothing and names nothing. Beside a non-blank label, an ariaLabel that does not contain the label’s words as one run of whole words is refused by mount and update with "ariaLabel" must contain the text of "label" ("<label>" is not in "<name>"). Over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in all seven palettes the label clears 4.5:1. The label is drawn in target’s face and size and in the body ink in both states, so the state is told by the track and the announced state, never by the label’s ink. The labelled switch is not held to the 78px cap: its label wraps at its spaces up to the width of target, the button growing taller to hold every line with the track centred against them, and it is never clipped or ellipsised. A setting’s name of one to four words keeps the label to one line; a sentence about the setting goes in the text aria-describedby points at. Pass label or aria-labelledby, not both. Where both are passed, the element aria-labelledby names is the switch’s name, which need not hold the words the switch draws. ariaLabel is the switch’s name where label is absent or blank, and is then required whether or not you pass aria-labelledby; beside a label it replaces the label’s words as the name, and must hold them. It is final display text, the same in both states, because aria-pressed or aria-checked says which holds. ariaLabel and label name the setting so that “pressed” or “on” means the setting is in effect: “Group by category”, “Hidden tasks”. Neither states a position, so no “on”, “off”, “show” or “hide” at its start or end, and never a negation such as “Do not group” (which reads “do not group, pressed”). Where you mount the switch without label, draw the setting’s name as visible text beside the switch, from one string that you also pass as ariaLabel, and pass both again in any update that changes the text, so the spoken name always contains the words the user sees; that text does not press the switch unless you wire it to onclick, so where your words must press the switch, pass them as label. An ariaLabel of white space alone is dropped and names nothing, so never rely on one. aria-labelledby is an aria prop: Fabricate writes it on the button. It is the id of your element that holds the visible name and nothing else, or several such ids separated by spaces, in the tree that holds target. The element may sit beside target; it need not be inside it. When at least one id names an element, that element’s text is the switch’s name and ariaLabel is not read. When none does, the switch is named by ariaLabel, so a mistyped id never leaves it nameless. aria-describedby is an aria prop: Fabricate writes it on the button. It is the id of one element of your own, or several ids separated by spaces, holding a sentence that is visible text beside the switch and that says what the setting does without repeating its name. Each id must exist in the tree that holds target while the switch is shown, and the element it names, which may sit beside target and need not be inside it, must not be hidden; an id that does not exist is skipped and the others are still read. The switch has no unavailable state at version 1. Keep the switch of a setting the user cannot change right now enabled. Answer its press with the reason, in a Notice or a notification of your own, and pass on unchanged; do not draw a setting that can never change here as a switch. Say that a setting is unavailable in the visible text aria-describedby points at too, so it is heard when the switch takes focus, not only after a press. The switch’s track is drawn the same in the Manager, the player window and, under the standalone style root, a companion’s own window or dialog. Foundry gives a button a minimum height of 2em of its own font size, so in a Foundry window the switch’s button is 24px tall at an inherited font size of 12px or less and 2em tall above that. Where Foundry resizes buttons by container it follows that rule instead (2rem inside a .standard-form or a dialog’s button row, 2.5rem for a direct child of a form footer), and the 22px track is centred in the button. Give target display: flex and align-items: center, and centre your own label against the switch. A labelled button is as wide as its track, its gap and its label, up to the width of target, and, in a Foundry window, grows past that height only as its label wraps. A wrapped label makes the button as wide as target, so its keyboard ring reaches 4px past target’s edge; give target that much room where it clips. The button is the only focusable element Fabricate draws in target, inside the standalone style root in a target with no Fabricate root, so target.querySelector('button') reaches it. An update keeps the same button, so focus stays on it while its state changes; destroy removes it, so where it holds focus, move focus first, as Ownership and theme states. The keyboard ring is the accent, 2px wide and 2px clear of the button, its label included, so it reaches 4px beyond it on every side; leave that much inside any edge of your own that clips. The switch states whether it is on to assistive technology with aria-pressed, or with aria-checked under semantics switch; how it looks does not carry the state on its own. Under forced colours the switch draws in system colours and keeps its state visible, and its label takes the system text colour. Give a switch you mount inside a .tabs element no data-group, because Foundry’s changeTab writes aria-pressed and toggles active on every button inside a .tabs element of that window whose own data-group names the tab group it changes. Its track and knob sizes, its button’s width, its 78px cap on a switch without label, its label’s line height, its colours beyond what this section states, and what it draws for an on value other than true or false are private. Rest data-* is for your own hooks; name them for your module, as data-<module-id>-…. They land on the button itself, so data-keyboard-focus, data-action, data-cursor, every data-tooltip name, and the two names Fabricate’s own stylesheet reads off its own buttons, data-validation-focused and data-essence-sort-direction, are refused with "<key>" is reserved on StatusToggle. The switch therefore opens no tooltip and keeps its own cursor, so the pointer is shown its name only as its label or your text beside it, and what the setting does goes in text beside it, tied to it with aria-describedby. A Fabricate that predates label refuses it with "label" is not a data attribute, which describe('StatusToggle').props shows; adding it is additive, and the entry stays at version 1.
A worked switch follows: a setting of your own, named by the label you draw beside it.
// After `load(['StatusToggle'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the switch describes none: draw your own control there.
if (fabUi?.describe?.('StatusToggle')?.props['aria-labelledby']?.kind !== 'aria') return;
// Your label beside `target`, in the same Fabricate window: <span id="acme-group-label">Group by category</span>.
const name = target.ownerDocument.getElementById('acme-group-label').textContent;
target.style.display = 'flex';
target.style.alignItems = 'center';
let grouped = acmeSettings.groupByCategory;
const props = () => ({
on: grouped,
ariaLabel: name, // The same text the label draws.
'aria-labelledby': 'acme-group-label',
onclick: () => {
grouped = !grouped;
acmeSettings.groupByCategory = grouped; // Your own state first.
toggle.update(props()); // Every prop again, with the new `on`.
},
});
const toggle = fabUi.mount('StatusToggle', { target, props: props() });
A switch whose words press it passes them as label instead, where the running Fabricate publishes it.
// After `load(['StatusToggle'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
if (fabUi?.describe?.('StatusToggle')?.props.label?.kind !== 'text') return; // Draw your own label.
let required = acmeStage.required;
const props = () => ({
on: required,
label: 'Required', // Drawn inside the switch, and its name.
'aria-describedby': 'acme-required-hint', // Your own sentence beside the switch.
onclick: () => {
required = !required;
acmeStage.required = required;
toggle.update(props());
},
});
const toggle = fabUi.mount('StatusToggle', { target, props: props() });
Stepper
Stepper draws the design system’s stepper: a native <input type="number">, or a text field where format is set, between a decrement and an increment <button>, for a number the user types or steps. The input is the control, so the number is always typeable. value is required and is the finite number the stepper holds. A value that is not a finite number is outside the contract, and what is drawn for it is private. ariaLabel is required and is the input’s name, final display text naming the quantity, as “Days to credit”. decrementLabel and incrementLabel are required and name the two buttons from the same words: “Decrease days to credit”, “Increase days to credit”. The buttons’ faces are a minus and a plus glyph alone, and no tooltip shows either name but the one decrementTooltip or incrementTooltip passes. Draw the quantity’s name as visible text beside the stepper, and make ariaLabel contain those words. A name of white space alone leaves the control with no name, so never pass one. To return focus to a stepper, focus its input, target.querySelector('input'). decrementTooltip and incrementTooltip are optional final display text, each its button’s tooltip, a hint that differs from the button’s name, as “One day fewer” beside the name “Decrease days to credit”; one that is not a string, or is blank, writes none. While one is open Foundry sets aria-describedby to tooltip on that button, so a screen reader may read it as the button’s description, and a tooltip that repeats the name is read twice; neither replaces its button’s name. Fabricate writes each as its button’s data-tooltip-text, which Foundry’s own hover listener shows as plain text after a delay, and opens it under keyboard focus, only under :focus-visible, through game.tooltip, closing it on blur, a press, Escape, destroy and an update that changes that button’s tooltip or disables it, through disabled or a bound, as the IconButton section states; Escape is not stopped, and whether Foundry’s dismiss keybinding then also runs is not measured. A Fabricate that predates them refuses each with "<key>" is not a prop of Stepper, which describe('Stepper').props shows by leaving it out. min and max are optional finite numbers, the inclusive bounds; an absent one leaves that side open. step is an optional positive number, 1 when absent, which each button press adds or removes exactly; the Up and Down arrow keys and the wheel over the focused input move the input to the next point of the grid min + k·step, counted from the browser’s step base when min is absent, so a number off that grid is reported as such. Outside this, what is drawn for min, max or step is private. The arrow keys and the wheel step to the next point on the grid from min, which is not always value ± step, so check what you are given. disabled is true or false, and false when absent. true disables the input and both buttons together and draws the stepper dimmed, so it takes no focus, is left out of the tab order and reports nothing. Use it for a quantity the user may read but cannot change right now, with the reason in text beside it, because a keyboard or screen-reader user tabs past a disabled stepper and nothing at it can say why. Never pass true while the input or a button holds focus, an update made inside onChange included: move focus to another control of yours first. The dimmed stepper is not held to the contrast floor. allowUnset is true or false, and false when absent. true is for a quantity that can be absent: value may then be null, which draws the input blank, and clearing the input calls onChange with null. Pass null back to leave the quantity unset, or a number to set it; if you pass value unchanged the input shows it again once it loses focus, as for a refused number. An unset stepper has no bound to stop at, so neither button is disabled, and a press starts from min, or from 0 where min is absent: the increment button reports one step above that start and the decrement button one step below it, each clamped to min and max. Without allowUnset a value of null is outside the contract, and what is drawn for it is private. fill is true or false, and false when absent. true stretches the stepper across the width of target and the input takes the room the two buttons leave, so give target the width you want it to fill; absent, the stepper hugs its content. The filled stepper is 38px tall, or as tall as the size rung you state, 26px or 34px, as stated for size. The input’s own width never holds target wider, so in a flex row or a grid column a filled stepper narrows with the room it is given down to little more than its two buttons’ width. density is default or comfortable, and default when absent. comfortable paints the two buttons at 24 by 24 CSS pixels, where the default paints them 22 by 22 inside a 24 by 24 pointer target, so the stepper is a little taller and wider; every pointer target is at least 24 by 24 at either density. What the stepper draws for a value outside the set is private; today that is the default density. size is 26, '26', 34 or '34', a number or its string, and absent draws the default: 26 draws the dense rung, 26px tall and as wide as the default, with no padding inside the stepper’s edge, so each step button fills a 24 by 24 cell to that edge, its own 24 by 24 pointer target, and the input a 24px-tall one (WCAG 2.2 success criterion 2.5.8). 34 draws the toolbar rung, level with a Field, Select, SearchField or SegmentedControl at its 34px rung: 34px tall and as wide as the default, with the default 2px padding inside the stepper’s edge and their 9px corner, the input filling the 28px row between the two buttons, and each button drawn 22 by 22 inside its 24 by 24 pointer target, as at the default rung. Any other value, 28, '28', '27', ' 26', '34px' and true among them, draws the default, 28px tall, and nothing is coerced; density: 'comfortable' draws 30px. Each rung outranks density, so comfortable beside it draws the same 26px or 34px stepper, and under fill it sets the stepper’s height across target, 26px or 34px, where a filled stepper with no rung stays 38px tall, so adding 34 changes nothing for a fill you mount today. No rung below 26 is published, because one would draw a step button under its 24 by 24 target. A Fabricate that predates size refuses it with "size" is not a prop of Stepper, which describe('Stepper').props shows by leaving it out; adding it is additive, and the entry stays at version 1. A Fabricate that publishes size but predates 34 draws 34 and '34' as the default rung, 28px tall or 38px under fill, and refuses nothing, so describe cannot tell the two apart; adding the value is additive, and the entry stays at version 1. The stepper steps by one step or one stop each way: a row of preset steps around a figure, as −5, −1, +1 and +5, is yours, drawn as published Buttons beside a Field, because each of its presses is an action of its own rather than one value’s step. placeholder is optional text, shown in the input while it is empty. It shows only while the input is empty, which is a null value under allowUnset, and under format only where there is no nullLabel, because a nullLabel draws its words instead; pass the text already localised and never rely on it as a name, because ariaLabel names the input and a placeholder does not. Fabricate draws it in the muted ink, which clears the contrast floor, and a placeholder that is not text is outside the contract. format is signed or unlimited, and absent for the plain number field. Either value draws a text field with the spinbutton role in place of the number field, and the field reports a number only when the user presses Enter or it loses focus, where the number field reports on every keystroke. A signed field draws a positive number with a leading plus, as +5, zero as 0 and a negative number with a hyphen-minus, as -5, and reads an optional plus, hyphen-minus or true minus sign followed by digits with an optional decimal point, as 1.5, .5 or 5.; any other text, such as 1e3 or 5%, is not a number. The signed field asks the browser for its text keypad, inputmode="text", because a decimal keypad shows no minus key on some touch devices, and an unlimited field asks for the decimal keypad, inputmode="decimal". An unlimited field draws every number but zero as itself, with no plus, and draws 0 as the nullLabel words, as “No limit”, for a quantity whose zero means there is none; it takes those words in any case, or 0, as that endpoint, and reports the endpoint as 0, never null. Without nullLabel, an unlimited field draws 0 as the number, and allowUnset is outside the contract. An unlimited field is meant for a min of 0: a min above 0 is outside the contract, and with no min a negative number is reachable and the endpoint sits mid-range; a typed 0 selects the endpoint before min clamps it. Under either value the field restores the displayed text when what was typed is empty or no number, and clamps a typed number to min and max. Text that is no number is restored silently, with no call to onChange, so show any refusal message in its own live region. Both buttons and the Up and Down keys move to the next stop above or below the held number, or by step clamped to min and max where stops is empty, and Home and End move to the lowest and highest stop, or to min and max where there are none. Enter in the field never submits a <form>, and Escape, while the typed text differs from the displayed text, restores the displayed text and goes no further, so it closes no window; with no such difference Escape is not caught. The field carries aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext, the last being the displayed text and the endpoint carrying no aria-valuenow, and the wheel over the focused field steps nothing. Under format where allowUnset is true and there is no nullLabel, a null value draws the field blank, and clearing the field then pressing Enter or leaving it reports null. stops is an optional array of finite numbers, the values the buttons and the Up and Down keys step between under format. Fabricate sorts it ascending and drops repeats and any entry that is not a finite number, and a stops that is not an array counts as none. A press moves to the nearest stop strictly above or below the held number, so a held number on no stop stays exact until the user steps it, and a typed number is clamped to min and max and never moved to a stop. A stop outside min or max stays reachable by both buttons, the Up and Down keys, Home and End, while a typed number is clamped, and aria-valuemin and aria-valuemax come from the lowest and highest stop. Without format it changes nothing. nullLabel is optional text, the words drawn for the one state that is not a number. Under format it names null for a signed field: value may then be null, which draws the words one step below the lowest stop, a press down from the lowest stop reports null, and typing the words, in any case, reports null; the decrement button is disabled there. Under unlimited it names 0, as stated for format, and the endpoint’s field is drawn in the muted ink and, unfilled and horizontal, widens to the words’ length. A nullLabel that is not a non-empty string counts as none, and without format it changes nothing. Fabricate coerces none of format, stops, nullLabel and placeholder: a format other than exactly signed or unlimited, a boolean, a number or another case among them, draws the plain number field, and stops and nullLabel then change nothing. Fabricate coerces none of disabled, allowUnset and fill to a boolean, so only true and false are in the contract: the string 'false' disables the stepper, allows it to be unset and stretches it. A Fabricate that predates disabled, allowUnset, fill, density, placeholder, format, stops and nullLabel refuses each with "<key>" is not a prop of Stepper, and describe('Stepper').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. onChange is a required callback, called with one argument, a number, each time an edit leaves the input holding a number that differs from value: a button press, an arrow key, a turn of the wheel over the focused input, or a keystroke; and again when the input loses focus holding such a number, so if you refused the earlier call you are told again. Where allowUnset is true the argument is null when an edit clears the input or leaves it holding no number, a lone minus sign among them. Under format it is called when the user presses Enter, a button, an arrow key, Home or End, or the field loses focus, and never per keystroke, with 0 for the unlimited endpoint and null for the signed one. Losing focus includes the input leaving the document as its window closes or a Foundry 14 window detaches, so do not assume the window is open when onChange runs; a mount you have destroyed reports nothing. The argument is the number edited, clamped to min and max and not rounded to step, so if you hold whole numbers, round it and pass your own value back. Pass an accepted value back in the same onChange handler, before any await; a later update draws after the field has shown the held value. An edit that clamps to value, leaves the input empty (unless allowUnset is true, which reports null) or leaves it holding no number is not reported. onChange is spelt in camel case, unlike Button’s and StatusToggle’s onclick. The input changes itself first: what the user types or steps shows at once, and a button press shows the new number when your update passes it. To refuse a number, pass value unchanged. The input shows what was typed until it loses focus, and Fabricate then replaces it with value, so say why in a live region of your own. Fabricate announces nothing when it restores a refused value; explain a refusal in your own live region. At min the decrement button, and at max the increment button, is natively disabled and dimmed, which takes it out of the tab order. Before an update that brings value to a bound, if the button toward that bound holds focus, move focus to the input, target.querySelector('input'), in the same handler. Beyond its bounds, the stepper’s one unavailable state is disabled. Where the quantity is not worth showing at all, destroy the stepper, moving focus first if one of its parts holds it, and show the number as text of your own. Answer a refused edit in text of your own, in a live region. The input takes the keys a number field takes, Up and Down among them; the buttons are pressed by pointer, Enter or Space and never submit. The stepper does not catch Escape, except under format as stated for it: the input holds Foundry’s keybindings off, so Escape in it closes a window only where Ownership and theme says so. Without format, in a <form>, Enter in the input submits it as implicit submission does, with or without a submit button where the input is the form’s only text field, and each step fires a bubbling change that a form with submitOnChange submits on, so mount the stepper in no <form>, Foundry’s or your own. Under format Enter never submits, but the bubbling change the browser fires when the field loses focus after a typed edit still reaches such a form. Stepper takes no rest props, so a data-* prop, an id and a title are refused with "<key>" is not a prop of Stepper. Stepper is drawn the same in the Manager, the player window and, under the standalone style root, your own window that holds target in no <form>. The Manager’s text-field baseline draws no box on the format field. A DialogV2’s content is always a <form>, so do not mount the stepper in one, as the sentence on Enter above states. Give target display: flex and align your own label to the stepper by centring. The input and the two buttons are the only focusable elements inside target. An update keeps all three, so focus stays where it is; destroy removes them, so where one holds focus, move focus first, as Ownership and theme states. The keyboard ring is the accent, 2px wide, drawn at the part’s own edge, or 1px outside it for the input under fill and for the buttons under comfortable, or straddling the part’s edge by 1px at size 26, where size 34 draws it as the default rung does, and inside the stepper’s own outer edge in every case, so leave no room for it, provided nothing of your own clips inside the stepper’s box. Its sizes, glyphs, colours, and what it draws for a value, min, max or step outside its contract, for a density outside its set or for min above max are private.
A worked stepper follows: a number of days to credit, which you hold in whole days and refuse below one.
// After `load(['Stepper'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the stepper describes none: draw your own number field there.
if (fabUi?.describe?.('Stepper')?.props.onChange?.kind !== 'callback') return;
// Your label beside `target`, in the same Fabricate window: <span>Days to credit</span>,
// and a live region of your own for a refusal: <p id="acme-credit-note" aria-live="polite"></p>.
const note = target.ownerDocument.getElementById('acme-credit-note');
target.style.display = 'flex';
target.style.alignItems = 'center';
const MOST_DAYS = 30;
let days = acmeCredit.days;
const props = () => ({
value: days,
max: MOST_DAYS,
ariaLabel: 'Days to credit', // The words your label draws.
decrementLabel: 'Decrease days to credit',
incrementLabel: 'Increase days to credit',
onChange: (next) => {
const whole = Math.round(next); // The argument is not rounded to the step.
if (whole < 1) {
// Pass nothing new: the input shows the typed number until it loses focus, then `days`.
// Fabricate announces nothing as it restores `days`, so your live region says why.
note.textContent = 'Credit at least one day.';
return;
}
note.textContent = '';
const input = target.querySelector('input');
const focused = target.ownerDocument.activeElement;
// The increment button disables at the bound, so move focus off it first.
if (whole === MOST_DAYS && focused !== input && target.contains(focused)) input.focus();
days = whole;
acmeCredit.days = days; // Your own state first.
// Every prop again, with the new `value`, in this handler and before any `await`:
// a later `update` draws after the field has shown the held value.
stepper.update(props());
},
});
const stepper = fabUi.mount('Stepper', { target, props: props() });
SearchField
SearchField draws the design system’s search field: a native <input type="search"> inside a <label> root that also draws a decorative glyph, for a query that narrows a list already on screen and commits nothing. The input is the only focusable element inside target, so to return focus to the field, focus target.querySelector('input'). value is the query, a string, and is '' when absent. A value that is not a string is outside the contract, and what is drawn for it is private. It is a value prop: the field changes it itself as the user types, and an update that omits it keeps the current query, so you need not pass the query back on every update. onValueChange is called with two strings, (next, previous), each time an edit of the user’s changes the query: a keystroke, a paste or a cut, and a clear the browser makes from the field’s cancel button or on Escape, which reports ''. Whether the browser draws a cancel button or clears on Escape is the browser’s: Chromium, and so Foundry’s desktop app, does both. It is not called by mount, update, Enter or the field losing focus. To refuse or transform a query, pass the query you keep back through update before the call returns, and the field shows it before the user’s input event has finished dispatching; the replaced query moves the caret to the end and ends any IME composition in progress. placeholder is optional final display text shown while the field is empty, and is not the field’s name. ariaLabel is required and is the input’s name, final display text naming what is searched, as “Search recipes”. The field draws no caption, so draw the same words as visible text beside it, and never pass a name of white space alone, which leaves the control with no name. density is 'default', 'toolbar' or 'inline' and defaults to 'default': it is the shell’s height, 'default' 38px at radius 9 and 'toolbar' and 'inline' the rungs of those names Select’s size draws, 34px at radius 9 and 30px at radius 7, each at the default shell’s fill, type and glyph; any other value, 'compact' included, draws 'default'. A search field at 'toolbar' or 'inline' stands as tall as a Select of that size beside it, so the row is one height; the retired 32px height is not a rung, and Fabricate’s own compact search, the one 'compact' draws for Fabricate’s callers, is not published. countLabel is optional final display text drawn after the input inside the shell, as “12 found” or “3 chosen”, on one line in the placeholder’s muted ink, and the input yields it the width it needs, up to half the shell. Past that it ends in an ellipsis, though its region still holds the whole text. '' or absence draws none. Keep the count short, a figure and a word, as “12 found”, because past half the shell it is cut. It is a polite status: Fabricate always draws its region, an element with role="status" that is empty while no count is given, so when an update writes or changes the text, a screen reader is expected to announce the whole new text, once, after what it is reading. It is not expected to be announced when the field is mounted with it, when an update passes the same text, or when an update changes any other key or the user types, because none of those changes the region; an update that drops the count empties the region, which is not expected to be announced either. How a screen reader treats a live region is the screen reader’s, and it varies between them, so the count is never the only place the result is told. While the user types, update countLabel after a short pause rather than on every keystroke, so each count does not queue behind the last. It is neither the input’s name nor its description, so a screen reader that reaches the input reads ariaLabel alone, and reads the count after it in reading order. Its muted ink clears 4.5:1 on the shell over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and not over --fab-bg-3, so do not draw a search field over --fab-bg-3. A Fabricate that predates density and countLabel refuses each with "<key>" is not a data attribute, and describe('SearchField').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. The field has no name, so it adds nothing to a form’s data, and a form with submitOnChange still submits on the bubbling change the input fires when it loses focus after an edit.
- Enter in the input, outside IME composition, cancels the implicit submission of the
<form>the input is in, so the field never submits a form, and reports nothing. - In a DialogV2 that wants Enter to confirm, handle Enter in your own listener above
target, because the field cancels the form’s implicit submission. - It stops the propagation of no key: every key reaches your listener above
target, the input holds Foundry’s keybindings off, and Escape closes a window only where Ownership and theme says so. - In a DialogV2, Escape closes the dialog, because the dialog listens for it on its own element. Whether the query is cleared first is not stated. Stop it in your own
keydownif you must keep the dialog open.
Rest data-* props land on the <label> root, never on the input, so no rest name is reserved. SearchField is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, as the shell of its density, 38px at radius 9 by default; it fills the width of target, so give target display: flex. The keyboard mark is the design system’s text-field variant for a field whose wrapper draws the box: while the input holds focus the shell’s 1px border takes the accent at every density and the input draws no ring of its own, so leave no room for one. The lit border clears 3:1 against the shell over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 and against those grounds beyond its edge in every palette, and not over --fab-bg-3, where two palettes fall short. An update keeps the input, so focus and the caret stay where they are unless the query is replaced; destroy removes it, so where it holds focus, move focus first, as Ownership and theme states. Its sizes beyond its height and corner, its glyph and colours beyond what this section states, and what it draws for a value that is not a string are private. label, ariaLabelledBy, icon, onChange and inputProps are not published at version 1, so a class or any of those is refused as a rest prop.
A worked search field follows: a filter over your own list of recipes, which you hold trimmed.
// After `load(['SearchField'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the value prop describes no search field: draw your own there.
if (fabUi?.describe?.('SearchField')?.props.value?.kind !== 'value') return;
// Your text above `target`, in the same Fabricate window: <span>Search recipes</span>.
target.style.display = 'flex';
const props = () => ({
ariaLabel: 'Search recipes', // The words your text draws.
placeholder: 'Name or tag',
onValueChange: (next) => {
const kept = next.trimStart(); // Your own rule for the query.
if (kept !== next) search.update({ ...props(), value: kept }); // Before any `await`.
acmeRecipes.filter(kept); // Your own list narrows; the field commits nothing.
},
});
const search = fabUi.mount('SearchField', { target, props: props() });
// Later, to clear the query from your own reset control:
search.update({ ...props(), value: '' }); // Draws `''` without calling `onValueChange`.
const query = search.value('value'); // The query the field holds now.
Select
Select draws the design system’s select: a <button> trigger with role="combobox" that opens a list of options in an overlay, for one choice from a short, known set that commits as it is made. The trigger is the only focusable element inside target, so to return focus to the select, focus target.querySelector('button'). options is required and lists the choices in drawn order, each { value, label }: value is a string or a number, unique as a string, and label is required final display text, the option’s whole accessible name and what the trigger shows while it is chosen. Two values that are the same string, such as 1 and '1', are outside the contract, because the list cannot draw two rows that share one. Opening the list then ends the mount as a fault, which empties target and reports to onFault, as Mounting, updating and destroying states. A member other than value and label is private, and an empty options, which mount and update both accept, opens a list that draws nothing and says nothing, so do not offer an empty select. value is the chosen option’s value, matched by ===, so 25 and '25' differ; absent, null, or matching no option, the trigger shows placeholder. A value that is neither a string, a number nor null is outside the contract, and what is drawn for it is private. onChange is a required callback, called with one argument, the chosen option’s value exactly as options passed it, so a number stays a number, each time the user chooses an option by pointer or by Enter, the option already chosen included. It is not called by mount, update, opening or closing the list, Escape or an outside press. The select changes nothing itself: the trigger shows the new choice when your update passes it as value, so to refuse a choice, pass value unchanged. ariaLabel is required and names the trigger and its list, final display text naming the choice, as “Rows per page”. The select draws no caption, so draw the same words as visible text beside it, and never pass a name of white space alone, which leaves the control with no name. placeholder is optional final display text the trigger shows while no option is chosen, and is not the select’s name. size is form, inline or toolbar, and defaults to form: the 38px trigger on --fab-surface-soft, the 30px trigger on --fab-bg-2 for a row, and the 34px trigger on --fab-bg-1 for a toolbar, each with its own list width. fill is true or false, and false when absent: true stretches the trigger across the width of target at every size, so give target the width of the column you want, and the trigger keeps that width whichever option is chosen; absent, the trigger hugs its label, so a select whose options differ in length changes width as the user chooses. Under fill a label longer than the trigger ends in an ellipsis and the chevron stays at the trailing edge, in either direction, and the list opens against the filled trigger as it opens against any. Fabricate coerces nothing to fill: only true stretches the trigger, and 'true' or 1 draws it hugging its label. fill replaces sizing the trigger with a descendant rule of your own wrapper, which names a part of the component and so is outside the contract; no width is published, because the column’s width is yours, on target, and fill makes the trigger take it. Under fill the trigger’s edge is target’s, so a keyboard focus mark drawn outside the trigger falls outside target; leave room for it there, unclipped. A Fabricate that predates fill refuses it with "fill" is not a prop of Select, which describe('Select').props shows by leaving it out; adding it is additive, and the entry stays at version 1.
- A press on the trigger opens the list and a second press closes it; Enter and Space press the trigger as they press any button, except that Enter while an option is active chooses it and Space inside a run of typed characters is typed.
- While the list is closed, ArrowDown and Home open it at its first option, ArrowUp and End at its last, Alt with ArrowDown opens it with no option active, and a printable character opens it at the next option whose label starts with what has been typed.
- While it is open, ArrowUp, ArrowDown, Home, End and a printable character move the active option, which the trigger names with
aria-activedescendant, and Enter chooses it; focus stays on the trigger throughout, and the chosen option carries a tick and a fill. - Escape and a press outside the list close it without choosing; a choice closes it and returns focus to the trigger.
- The trigger stops the propagation of every key but Tab, with or without Shift, pressed while it holds focus, so your listener above
targethears Tab and no other key from it, and while the trigger holds focus Foundry’s Escape keybinding closes no window, an open ApplicationV1Dialogincluded, because that dialog listens for Escape on the document, which the key never reaches. - In a DialogV2, Escape on the trigger does not close the dialog; handle Escape in your own listener on the trigger or move focus first.
- Tab and Shift+Tab close an open list without calling
onChangeand move focus as the browser does, and your listener abovetargethears the Tab. - The list also closes without choosing, moving no focus, once focus moves to an element outside the trigger and the list; focus leaving the browser window, or moving between the main window and a detached one, closes nothing.
- A press on the trigger does not bubble out of it as a
click, and a press inside the open list does not bubble out of the list, so yourclicklistener abovetargetor on theoverlayHosthears neither.
The list is the component’s overlay, so describe('Select').overlays is true, and it is drawn in the host Overlays picks when it opens. Pass an overlayHost inside the same Fabricate window, or none, because the list’s hidden live region is clipped only under a .fabricate ancestor; in your own window or dialog pass none, and the list opens on the standalone layer. The list opens against the trigger, and its placement inside the host is private. Select takes no rest props, so a data-* prop is refused with "<key>" is not a prop of Select. Its trigger’s height, corner, type size, weight and fill are drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, and its typeface and line height are inherited under the Manager and are Foundry’s own button face elsewhere, as for every select of Fabricate’s own; its open list is drawn the same on the standalone layer as in the player window. While the trigger holds focus by keyboard it draws the accent ring, 2px wide and 2px clear of the trigger, so it reaches 4px beyond the trigger on every side, and its 1px border also takes --fab-accent-border; a pointer press draws no ring. Leave that much inside any edge of your own that clips, a scrolling container’s among them. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and against the trigger’s own fill over each, at every size, and the border alone, which is under 3:1 against the unfocused border, is not what marks focus. Under forced colours the ring is kept, drawn in a system colour apart from the ground. An update keeps the trigger, so focus stays on it, and an update while the list is open redraws the list in place; destroy removes the trigger and closes the list, so where the trigger holds focus, move focus first, as Ownership and theme states. Foundry 14 gives you no signal when it moves a Fabricate window to or from a detached window, and a select needs none: each list opened after the move is placed and heard in the window that then holds the trigger, as Overlays states. Its sizes beyond each rung’s height and corner, its tick, chevron and colours beyond what this section states, what it draws for a member of options other than value and label or for a value outside its contract, and the list’s placement and width are private. label, hint, error, ariaLabelledBy, ariaDescribedBy, id, name, showTick, minWidth, maxWidth, triggerProps, triggerTitle, readonly, disabled, invalid, mono and icon are not published at version 1, so a class or any of those is refused with "<key>" is not a prop of Select.
A worked select follows: a page size for your own list of recipes, which you hold as a number.
// After `load(['Select'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the select describes none: draw your own control there.
if (fabUi?.describe?.('Select')?.overlays !== true) return;
// Your text beside `target`, in the same Fabricate window: <span>Rows per page</span>.
target.style.display = 'flex';
let pageSize = acmeRecipes.pageSize;
const props = () => ({
options: [
{ value: 10, label: 'Ten rows' },
{ value: 25, label: 'Twenty-five rows' },
],
value: pageSize,
ariaLabel: 'Rows per page', // The words your text draws.
size: 'inline',
onChange: (next) => {
pageSize = next; // A number, as `options` passed it.
acmeRecipes.setPageSize(pageSize); // Your own state first.
select.update(props()); // Every prop again, with the new `value`.
},
});
// Omit `overlayHost` to draw the list in the Fabricate window around `target`.
const select = fabUi.mount('Select', { target, props: props() });
StageBars
StageBars draws how far a staged process has come: one bar per stage, side by side, in a group, each bar a progressbar with its own value; it draws no control. stages is required and lists the stages in drawn order, each { name?, label?, valueText?, value, weight?, shares?, title? }: value is the stage’s fill, 0–100 and clamped, name is final display text drawn as the stage’s caption while numbered, and label is final display text that names the stage’s bar. A bar is named by its stage’s label, else its name, else, in a list of one stage only, by the group’s own name. So in a list of two or more stages each stage requires a label or a name: a stage with neither has no accessible name, which Fabricate does not refuse. valueText is final display text the bar announces as its reading in place of its percentage, as “40%, stage 3 of 4”, so state the percentage in it too. A stage whose valueText is absent, '' or not a string announces its percentage. Pass a non-blank string, because one of only spaces is written as it stands rather than replaced by the percentage. Naming valueText is additive, and the entry stays at version 1. A Fabricate that predates it ignores it and announces the percentage, and describe cannot tell you which one is running. weight is the stage’s share of the row: a finite number above zero, else 1, so the bars are each weight over the sum of the weights wide and a list that names none draws equal bars. A weight that is a numeric string reads 1, and a bar narrower than its caption cuts the caption off with an ellipsis. Naming weight is additive, and the entry stays at version 1: a Fabricate that predates it draws equal bars, and describe cannot tell you which one is running. A stage’s shares is an array of { weight, tone? }, read as FillBar’s shares are: two or more draw the stage’s fill as abutting shares, each weight over the sum of the weights wide, and the whole stack is as wide as the stage’s value. A share’s tone is one of FillBar’s sixteen tones and defaults to success, a tone outside them draws neutral, and a member of a share other than weight and tone is private and dropped from the copy Fabricate renders, so a color on a share paints nothing. A share’s weight sizes it within its own stage’s fill, and a stage’s weight sizes the stage’s bar within the row, so the two never mix. Two or more shares take the place of the stage’s state paint: the current stage draws no accent and a filled one no success, and the bar keeps its aria-current and its value; one share, none or a shares that is not an array draws the state’s paint as before. So if you want the current stage told apart on the bar itself, choose the current stage’s share tones for it, and say it in your text too. So say which stage is current and which are done as text beside the bars, and state each share as text too: the shares are colour and width alone, are not announced, and neighbouring tones can sit under 3:1 against each other. Against the default track 9 of the 448 readings of the sixteen tones on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in the seven palettes are under 3:1, all on --fab-bg-2 and six of them in foundry-native, the weakest success there at 2.3:1; against the thin track they read as the thin FillBar’s do, 20 of the 112 under 3:1 and none under 1.8:1. Naming shares is additive, and the entry stays at version 1: a Fabricate that predates it draws each stage in its state’s paint and refuses nothing, and describe cannot tell you which one is running, so the text beside the bars carries the shares on either. A stage’s title is final display text, a hint about the stage, as “Smelt: 3 of 5 days”, and Fabricate writes it as the bar’s data-tooltip-text where it is a non-blank string, numbered or not, so Foundry’s own hover listener shows it as plain text, never read as HTML, after a delay while the pointer rests on the bar. A title that is not a string, or is blank, writes none. The bar is no control and takes no focus, so the tooltip opens on pointer hover only and a keyboard or touch user never sees it: a title is a hint and never the only carrier of a stage’s state, so say each stage’s state and reading in its label or valueText and in your own text beside the bars. While it is open Foundry may describe the bar by it through aria-describedby, so a screen reader may read it too; no screen reader was tested. It is not the caption’s title: while numbered a named caption still carries its stage’s name as its native tooltip, so the bar and its caption each show their own under the pointer. So while numbered do not repeat the stage’s name in title: it is a pointer-only hint, so put in it what the caption does not say, as the days spent. Naming title is additive, and the entry stays at version 1: a Fabricate that predates it draws no tooltip and refuses nothing, and describe cannot tell you which one is running. A member other than name, label, valueText, value, weight, shares and title is private, id among them, and an empty stages draws the named group with no bar. gap is default or tight, and default when absent or any other value: tight draws a 2px gap between the bars where default draws 6px. A Fabricate that predates gap refuses it with "gap" is not a data attribute, and describe('StageBars').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. track is default or thin, and default when absent or any other value: thin draws each bar’s track as FillBar’s thin one is drawn, with no border and on --fab-bg-3 on any ground, but 6px tall, so the fill is the whole 6px rather than inset by the default track’s 1px border. Against your ground the thin track itself is faint, 1.0:1 to 2.9:1 over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in the seven palettes, and in foundry-native on --fab-bg-2 an empty stage cannot be seen at all: --fab-bg-3 there is a shade darker than --fab-bg-2, at 1.00:1, so pass numbered or state the stage count as text. Under forced colours the thin track keeps a 1px edge in the system text colour, as the default track’s border is drawn there, so each bar’s extent stays visible. Under forced colours the fill on either track is drawn solid in the system text colour, as FillBar’s is, and each bar keeps the track’s own 1px edge in that colour. Under forced colours the current stage’s track also draws a 2px Highlight outline, and a stage’s abutting shares are parted by a 1px Canvas line, so the current stage and the split of a stage are told without colour; neither is drawn otherwise. The stage states, done, current and to do, and a stage’s share split all draw the same solid fill there, so they are not told apart. So state each stage’s state and reading as text beside the track. On the thin track the state paints read against --fab-bg-3 as the thin FillBar’s tones do: the accent is under 3:1 in hearth-herb and ironblood-forge, the success in foundry-native, and the neutral in hearth-herb, ironblood-forge and starglass-arcana, the weakest the neutral in hearth-herb at 2.1:1, so aria-current and your text, never the colour, say which stage is current and which are done. A Fabricate that predates track refuses it with "track" is not a data attribute, and describe('StageBars').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. currentIndex is the index of the stage being worked, and defaults to 0: its bar carries aria-current="step" and takes the accent until it fills, a filled bar takes the success tone, and every other bar the neutral one. numbered is true or false, and defaults to true: while it is true each bar draws a caption beneath it, hidden from assistive technology, holding its position counted from 1 and then its name; a stage with no name draws its position alone. A caption is drawn on one line and cut off with an ellipsis where it is wider than its bar, so keep each name short. Each caption carries its stage’s name as its native tooltip (title), so a name the ellipsis cuts is shown whole under the pointer. A caption with no name carries none. ariaLabel is required and names the group, final display text, as “Forging progress”. It also names the one bar of a one-stage list whose stage has no label or name. Rest data-* attributes land on the group root. StageBars needs no Fabricate ancestor, so its root is any, and it draws the same under any ancestor. It is not a live region: an update redraws the bars in place and announces nothing. The default track’s height, each track’s corner, its gaps, its caption’s face, size and ink, each tone’s colours, and what it draws for a currentIndex outside the list are private. ariaLabelledBy is not published at version 1, so it is refused with "ariaLabelledBy" is not a data attribute.
A worked stage group follows: the stages of your own forging project, each named by its own title and read with its position.
// After `load(['StageBars'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
if (!fabUi?.components.includes('StageBars')) return;
// Your heading above `target`: <h3>Forging progress</h3>.
const props = () => ({
ariaLabel: 'Forging progress', // The words your heading draws.
currentIndex: acmeForge.stage,
stages: acmeForge.stages.map((stage, index, all) => ({
name: stage.title,
value: stage.percent,
// Your own words; they replace the percentage, so they state it too.
valueText: `${Math.floor(stage.percent)}%, stage ${index + 1} of ${all.length}`,
})),
});
const bars = fabUi.mount('StageBars', { target, props: props() });
// After your own stage advances, pass every prop again.
bars.update(props());
Field
Field draws the design system’s field: the column that stacks a caption over the control it heads, for one labelled entry of a form you draw. It draws no control, no caption and no text of its own: draw your caption and your control in its content slot. as is required and is div, the one host published at version 1; what it draws for any other value is private. A div field names no control, so give your caption an id and point the control’s aria-labelledby at it. Or mount a published Kicker with for set to the control’s id, which draws the caption as a <label for> and so names the control. children is a content slot whose element is a <div>; the field draws the content slot’s children in a column it spaces, in the order you append them: the caption first, the control beneath it. The column states --fab-text ink at 12.5px and weight 500, which your content inherits, and a text input or textarea there inherits its face from it unless face says otherwise. The caption is a child of the content slot’s element, never of the column, so Fabricate’s sheet draws it in the column’s type, never as a kicker. Fabricate’s own fields caption in the kicker type, so to match them mount a published Kicker with as span into your caption <span id> and give that span display: flex, which keeps the id on your element and the span exactly as tall as the kicker, as Kicker states. A text-like <input>, one whose type is text, url, email, tel or password or is absent, and a <textarea> you draw in the slot take the field’s chrome: the width of the column, a 1px --fab-border edge on a --fab-bg-1 fill and --fab-text ink, an input as tall as the field’s size, 38px at radius 9 by default, and a textarea at least 92px tall that resizes vertically. A <small> there takes the muted ink, for a hint beneath the control. Give the hint an id and add it to the control’s aria-describedby, so the hint is read with the control. A published control you draw there is drawn as it is in Fabricate’s own fields, and what the chrome draws on any other <input> is private. The keyboard ring of a text-like input, a number input under type 'number', or a textarea in the slot is the accent, 1px wide and inset 1px at every size, so it is drawn over the control’s own edge and you leave no room for it. It clears 3:1 against the control’s --fab-bg-1 fill in every palette, and against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 beyond its edge, and not against --fab-bg-3, where two palettes fall short, so draw the field on those four grounds. size is 26, 28, 30, 34 or 38 and defaults to 38: it is the height in CSS pixels of a text-like input, or a number input under type 'number', in the slot, a rung of the design system’s control-height ladder, at radius 7 for 26, 28 and 30 and radius 9 for 34 and 38; '26', '28', '30', '34' and '38', the string form Button’s size takes, draw the same rungs, and any other value draws 38. The ladder’s 44 is not a field rung, and a textarea keeps its own height at every size. face is 'sans', 'serif' or 'mono' and defaults to 'sans': 'sans' keeps the face the control inherits from the column, 'serif' draws the control’s text in the design system’s serif face, for a name, and 'mono' in its mono face, for a formula or a figure; any other value draws 'sans'. The face reaches a text-like input, a number input under type 'number', or a textarea in the slot, never your caption or hint, and the type size stays the column’s 12.5px. align is 'start', 'center' or 'end' and defaults to 'start': it is the text alignment of a text-like input, a number input under type 'number', or a textarea in the slot, and of its placeholder, so 'center' centres a figure such as a threshold; any other value, 'left', 'right' and 'Center' among them, draws 'start'. 'start' and 'end' follow the control’s own direction, so in a right-to-left document 'start' draws the text against the right edge and 'end' against the left; 'center' is the same in either. The alignment never reaches a <select> you draw in the slot, which is not part of the field’s chrome, or your caption or hint, and it moves no box, padding, keyboard ring or colour, so the control’s height, ring and contrast stay those this section states at every size and face. type is 'text' or 'number' and defaults to 'text': 'number' gives an <input type="number"> you draw in the slot the field’s chrome with no step buttons, the button-less numeric field; any other value draws 'text', and what the chrome draws on a number input then is private. The input keeps its own behaviour: the arrow keys step it by its step between its min and max, and a screen reader announces it as a spin button with its value, named by your caption as any control in the slot is. Chromium, and so Foundry’s desktop app, still changes a focused number input when the mouse wheel turns over it, so read its value on change and hold it to your own bounds. Mount a published Stepper where the user should see step buttons; a Stepper you mount in the slot keeps its own height, face, alignment and error state, because size, face, align and invalid never reach it, and a published Select or SearchField there keeps its own alignment too. invalid is true or false and defaults to false: true draws the error state on a text-like input, a number input under type 'number', or a textarea in the slot that also carries aria-invalid="true", a --fab-danger-border edge on a translucent --fab-danger-soft fill at the control’s own height; any other value, or a control without that attribute, draws none. The field cannot reach your control’s attributes, so keep the two signals together: set aria-invalid="true" on the control whenever you pass invalid true, and remove it when you pass false; a screen reader announces the control as invalid. Always draw a visible text message beneath an invalid control, ink it --fab-danger-text, give it an id and add that id to the control’s aria-describedby, so the message is read with the control; an icon you draw beside it is decorative, so give it aria-hidden="true". Colour alone does not carry the error: the danger edge falls short of 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and forced-colors mode removes the fill and the edge’s colour. The message’s --fab-danger-text ink clears 4.5:1 on those four grounds in every palette, where --fab-danger does not. The control’s --fab-text ink and the keyboard ring, drawn over the danger edge while the control holds focus, clear 4.5:1 and 3:1 on the error fill over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette. readOnly is true or false and defaults to false: true draws the read-only face on a text-like input, a number input under type 'number', or a textarea in the slot that also carries the readonly attribute, a dashed --fab-border edge on no fill, with the control’s own height and ink; any other value, or a control without that attribute, draws none. The field cannot reach your control’s attributes, so keep the two signals together: set readonly on the control whenever you pass readOnly true, and remove it when you pass false. The readonly attribute makes the value read-only and the face only shows it: the control stays focusable and in the tab order, its text can be selected and copied, and typing or deleting changes nothing. Chromium’s accessibility tree states a text input or a textarea with readonly as read-only and not disabled. A number input takes the face too, but the tree states it only as a spin button whose value cannot be set and does not state it as read-only, so prefer a text input for a read-only figure. Never use disabled for a value the user may read, because a disabled control leaves the tab order. The face is a dash and a missing fill, not a change of ink: the ink is --fab-text and clears 4.5:1, and the keyboard ring clears 3:1, on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette. The edge is the editable control’s own and falls short of 3:1 on those grounds in every palette, so the face is a hint and the announced state carries the meaning: where the user must know the value cannot be edited, say so in a visible caption or hint. The dash stays in forced-colors mode, where the system colours replace the rest. readOnly keeps what size, face, align and type write, and with invalid the danger edge colour and fill are drawn over the dash. It never reaches a published Stepper, Select or SearchField, or a <select>, in the slot. A Fabricate that predates size, face, type and invalid refuses each with "<key>" is not a data attribute, and describe('Field').props shows whether the running one publishes them; adding them is additive, and the entry stays at version 1. A Fabricate that predates align refuses it with "align" is not a data attribute, so check describe('Field').props.align before you pass it; adding it is additive, and the entry stays at version 1. A Fabricate that predates readOnly refuses it with "readOnly" is not a data attribute, so check describe('Field').props.readOnly before you pass it; adding it is additive, and the entry stays at version 1. Rest data-* attributes land on the column root. Field’s column and chrome come from Fabricate’s module sheet, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. Fabricate draws nothing focusable in the field: an update keeps the column and its content slot, so focus stays on a control you drew there; destroy removes them, so where that control holds focus, move focus first, as Ownership and theme states. The field never moves its content slot while it is requested. Its gap, its type figures beyond the column’s, the chrome’s figures and colours beyond what this section states, and how Fabricate redraws a field and its control in its own rows, cards and rails are private. The label and fieldset hosts of as, and a caption of its own, are not published at version 1. A class, label or caption is refused because a rest key must be a data-* attribute.
A worked field follows: a caption, a text input and a hint of your own, for the name of a recipe you hold.
// After `load(['Field', 'Kicker'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
if (!fabUi?.components.includes('Field')) return;
const field = fabUi.mount('Field', { target, props: { as: 'div', children: true } });
const slot = field.slot('children');
const caption = document.createElement('span');
caption.id = 'acme-recipe-name-caption'; // Unique in the document.
caption.style.display = 'flex';
const hint = document.createElement('small');
hint.id = 'acme-recipe-name-hint';
hint.textContent = 'Shown on the recipe card.';
const input = document.createElement('input');
input.type = 'text';
input.setAttribute('aria-labelledby', caption.id);
input.setAttribute('aria-describedby', hint.id);
input.value = acmeRecipe.name;
slot.append(caption, input, hint);
// The caption in the kicker type, named by the id on your own span.
fabUi.mount('Kicker', {
target: caption,
props: { as: 'span', children: 'Recipe name' },
});
// `field.destroy()` also destroys the kicker mounted in its content slot.
Well
Well draws the design system’s well, the container level below a card, for a group of related content inside a card’s content slot. It draws no control and no text of its own but its label. label is optional final display text, drawn as the well’s kicker in upper case above your content. With it the well is a group named by it, so a screen reader may read the label twice, as the group’s name and as the kicker’s text; without it, an unnamed <div> with no role. Pass sentence case. children is a content slot whose element is a <div>; the well draws the content slot’s children in normal flow below its kicker, with no gap of its own, inside its own padding, so add no padding. Fill the slot with one element of your own that lays out and spaces your content, as Mounting, updating and destroying states. Children you append to the slot directly, not inside that one element, lay out in ordinary block and inline flow: inline ones share a line and block ones keep their own margins. The label is drawn by a Kicker as p, so Kicker’s type and grounds apply; it is not a heading. Its fill is --fab-bg-1 inside a 1px --fab-border edge, or --fab-bg-2 inside a Fabricate dialog. A Fabricate dialog is the dialog Fabricate draws itself in its own window, or the Modal you mount, whose body is itself --fab-bg-1; a Foundry DialogV2 is not one. It states no ink or type, so your content inherits the Fabricate window’s ink from target, and a Kicker clears 4.5:1 on either untoned fill. tone is warning, success, accent or info; absent, or any other value, draws no tone, and nothing is coerced. It draws the well’s edge in the tone’s border colour on the tone’s translucent soft fill, in place of either fill, inside a Fabricate dialog too, so the well is tinted over the ground it sits on, as a toned InspectorCard is; under forced colours a toned well also draws a second 1px edge inset in its padding. Colour is never the only carrier of the state, and a tone’s edge falls short of 3:1 as the card’s does, so say the state in words in what you draw in the well. A toned well’s label inks --fab-text-secondary, which clears 4.5:1 on every tone’s fill over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, because the kicker’s muted ink falls short there. --fab-text-muted text of your own falls short of 4.5:1 on a toned fill over --fab-bg-1 and --fab-surface in one palette, over --fab-bg-0 in one at every tone but success, and over --fab-bg-2 in five or six, so draw small text in a toned well in --fab-text or --fab-text-secondary. A Fabricate that predates tone refuses it with "tone" is not a data attribute, and describe('Well').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. Never nest a well in a well: the design system has two container levels, the card and the well. Fabricate does not refuse a well nested in a well; this section only says not to. Rest data-* attributes land on the well’s root. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element that takes no focus. Well is drawn the same in the Manager, the player window and, under the standalone style root, a companion’s own window or dialog, but for its fill inside a Fabricate dialog. The well never moves its content slot while it is requested, and an update that adds or drops label keeps the slot in place. Fabricate draws nothing focusable in the well: an update keeps the well and its content slot, so focus stays on a control you drew there; destroy removes them, so where that control holds focus, move focus first, as Ownership and theme states. Its padding and corner figures, the space below its label, and how Fabricate draws a well in its own option groups and roll prompt are private. A class is refused because a rest key must be a data-* attribute.
A worked well follows: a labelled group of the reagents you hold for a batch, in a card mounted in a target of yours, for example in an extension target or a window of your own.
// After `load(['InspectorCard', 'Well'])` has resolved and `fabricate.ready` has fired.
// `target` is any element of yours, in a Fabricate window or in a window of your own.
const fabUi = game.fabricate?.api?.ui;
if (!fabUi?.components.includes('Well')) return;
const card = fabUi.mount('InspectorCard', { target, props: { children: true } });
const wellTarget = document.createElement('div');
card.slot('children').append(wellTarget); // The well's place, inside the card.
const well = fabUi.mount('Well', {
target: wellTarget,
props: { label: 'Chosen reagents', children: true },
});
// One element of your own lays out and spaces what the well holds.
const content = document.createElement('div');
content.style.display = 'flex';
content.style.flexDirection = 'column';
content.style.gap = '8px';
for (const reagent of acmeBatch.reagents) {
const line = document.createElement('p');
line.style.margin = '0'; // Foundry's own paragraph margin would add to the gap.
line.textContent = reagent.name;
content.append(line);
}
well.slot('children').append(content);
// `card.destroy()` also destroys the well mounted in its content slot.
Callout
Callout draws the design system’s callout: a standing statement, a rule or fact that is always true and stays put, beside a leading glyph in a rounded strip. It is never a live region and announces nothing, on mount or on update: a note the reader must hear when it appears is a Notice. tone is neutral, info, accent, warning, success or danger, and defaults to neutral; a tone outside that set draws neutral, so a tone added later is additive. info is a standing note about live state, warning a hazard the reader can still avoid, danger a standing consequence and success a standing confirmation; accent is colour alone and says nothing. It repaints the edge, the fill, the glyph and the title, and the body keeps its muted ink at every tone. Colour is never the only carrier and the glyph is hidden from assistive technology, so say the state in words in your title, text or items; the glyph each tone draws by default is private and two tones may share one, so the glyph never tells tones apart. title is optional final display text, a short line drawn above the text. It is not a heading. text is optional final display text, the note’s sentence. icon is optional Font Awesome classes for the leading glyph, hidden from assistive technology; absent, the tone’s own glyph is drawn. items is optional and is an array of { icon, lead, text } points drawn under the body as a list: lead and text are final display text, the lead inked --fab-text before the text, and icon is Font Awesome classes for the point’s glyph, hidden from assistive technology and inked as the leading glyph. Every member of an item is optional and draws nothing when absent or empty, an item that is not an object is skipped, and a value that is not an array draws no list. Pass no other member: one this line does not state is private, and a function in it throws "items" must not hold a function. The lead and the text are drawn one space apart, so punctuate the lead where the run would be ambiguous, as Moonpetal: before one held, two needed. An item with no icon releases the glyph column, so its text starts left of its glyph-led siblings’, so give every item of a list an icon, or none. actions is a content slot whose element is a <span>, drawn inside the strip after the body, so a note and the control that answers it are one object. At the default placement its host is a row that spaces the content slot’s children by gap, centres them on one line and never shrinks; unlike a Notice’s action it never drops beneath the body, so the body narrows to make room and a long label squeezes it: keep what you draw there short. actionsPlacement is 'inline' or 'below' and defaults to 'inline', the row above. 'below' draws the host as a column beneath the glyph and the body, as wide as the strip’s content box, which stacks the content slot’s children by gap and stretches each to that width, for a call to action under its note. Any other value draws 'inline'. Under it, a published Button you mount with fullWidth in a <span> of yours in the slot spans the strip, and the body keeps the whole row beside the glyph, at any width the strip is drawn at, 180px included. Keep the label short: where the strip is narrower than the label, the label wraps inside the button, and one that wraps onto more lines than the button holds spills past its edges, as Button states. The host follows the body in the DOM at either placement, so a screen reader and the Tab key reach what you draw there after the body. A Fabricate that predates actionsPlacement refuses it with "actionsPlacement" is not a data attribute, and describe('Callout').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. Fill it with phrasing content, a <span> for a mount target, for example of a published Button; content there inherits the strip’s muted ink and type. A published Button’s focus ring clears 3:1 against every tone’s fill on the four grounds named below. Give that button the neutral, primary, warning or danger role, never ghost or dashed, whose transparent face draws the label in the muted ink, which falls short on a tinted fill as the body does. It draws a <p> with no role unless it draws a title, an item or the actions slot, and then a <div> with role="note", because a paragraph cannot hold them. With none of title, text and items the strip is a bare glyph that says nothing, so never mount a callout without one of them; with actions alone it is a note holding just your control. An update that moves it between the two replaces its root element; the mount, its handle and its claim on target are unchanged, and while actions is requested the root stays the <div>, so no update moves the slot. Its ink and fill are its own, so its root is any and it needs no Fabricate ancestor: the body inks --fab-text-muted on the tone’s translucent fill over target’s ground, and the title inks --fab-text at neutral and the tone’s own text ink otherwise; it inherits target’s face. The title, an item’s lead and the glyphs clear their floors, 4.5:1 for text and 3:1 for a glyph, at every tone in every palette on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and the title does not on --fab-bg-3, so draw a callout on those four grounds. On a light ground, such as Foundry’s light application theme or a light-themed chat card, the translucent fills barely tint it and none of its text clears 4.5:1, so in a window of your own paint --fab-bg-1 on target. The body, its text, each item’s text and text you draw in actions, which inherits the same ink, is the muted ink over the tone’s fill: it clears 4.5:1 in every palette at neutral on those four grounds, at danger on --fab-bg-0, --fab-bg-1 and --fab-surface, and at success on --fab-bg-0. In the default palette alone it falls short on --fab-bg-1, a Fabricate window’s own ground, and on --fab-surface, at info (4.20:1), accent (4.08:1), warning (4.14:1) and success (4.27:1), and on --fab-bg-0 at info (4.49:1), accent (4.36:1) and warning (4.42:1). At every tone but neutral it falls short on --fab-bg-2, so inside an InspectorCard, in up to six of the seven palettes, the default among them; so say in title whatever the reader must not miss. Rest data-* attributes land on the root. Name them for your module, as data-<module-id>-…; data-callout-* names are the note’s own and private, so pass none: a value under one the note writes overwrites it. Do not pass data-action: the window dispatches a click on it (close closes the window), which makes a pointer-only control of an element that takes no focus. Fabricate draws nothing focusable in the note: an update that keeps actions keeps its slot, so focus stays on a control you drew there; one that omits actions, and destroy, remove that control, so where it holds focus, move focus first, as Ownership and theme states. Its padding, corner, edge, gap and type figures, the glyph each tone draws by default, and how Fabricate lays a callout out in its own entries and cards are private. A class is refused because a rest key must be a data-* attribute.
A worked note follows: the reagents a batch still lacks, with the control that answers it in the strip, mounted in a target of yours, for example in an extension target or a window of your own.
// After `load(['Callout', 'Button'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
if (!fabUi?.components.includes('Callout') || !fabUi.components.includes('Button')) return;
const note = fabUi.mount('Callout', {
target,
props: {
tone: 'warning',
title: 'Two reagents run short',
items: [
{ icon: 'fas fa-leaf', lead: 'Moonpetal:', text: 'one held, two needed' },
{ icon: 'fas fa-fire', lead: 'Ember salt:', text: 'none held' },
],
actions: true,
},
});
// A `<span>` mount target in the actions slot, a flex box so it is exactly as tall as the button.
const buttonTarget = document.createElement('span');
buttonTarget.style.display = 'flex';
note.slot('actions').append(buttonTarget);
fabUi.mount('Button', {
target: buttonTarget,
props: { role: 'neutral', children: 'Open the shopping list', onclick: () => acmeShop.open() },
});
// `note.destroy()` also destroys the button mounted in its actions slot.
IconButton
IconButton draws the design system’s icon button: a native <button type="button"> whose face is a glyph alone, for a verb its glyph says where a label does not fit, as a row’s remove control. A verb that needs its word to be understood is a published Button. icon is required and is the Font Awesome classes of the glyph, as fas fa-trash, drawn as an <i> hidden from assistive technology; it is the button’s whole face. ariaLabel is required and is the button’s name, final display text naming the verb and what it acts on, as “Remove Iron ingot”. It is the button’s whole accessible name and its tooltip, so a sighted user who cannot read the glyph is shown the words a screen reader speaks. A name of white space alone leaves the button with no name and an empty tooltip, so never pass one. role is neutral, primary, ghost, danger or ghost-danger, and defaults to neutral; a role outside that set draws neutral. It is the button’s visual role and sets no ARIA role: the button is a native <button> whatever role says. Each value names a verb, never a colour: neutral is the secondary verb. primary the leading verb of its cluster. ghost the quiet verb, drawn with no edge or fill at rest, for a control repeated on every row of a list. danger the destructive verb. And ghost-danger the destructive verb repeated on every row, as a row’s delete. A visual role is drawn and never announced, so a destructive role needs the verb in ariaLabel: “Delete Iron ingot”, never “Iron ingot”. Confirm a destructive press yourself, in a dialog of Foundry’s, before anything is written. size is '', '20', '22', '24' or '26', a string, and defaults to '': '' draws the default rung, and '20', '22', '24' and '26' a square of that many pixels at every role; what it draws for any other value is private. '20' and '22' draw the button below the 24px pointer target floor (WCAG 2.2 success criterion 2.5.8), so Fabricate widens its pointer target to 24 by 24 CSS pixels about its centre, 2px past each edge at '20' and 1px at '22', without moving the button or anything beside it; the keyboard ring is drawn from the button’s own edge, as at every rung. The widened target takes the pointer from whatever it overlaps, so stand two such buttons at least 4px apart at either rung, which also keeps their keyboard rings from crowding, put nothing of your own into that margin, and leave the margin inside any edge of your own that clips, which the ring’s 4px already asks. disabled is true or false. true draws the button as unavailable, takes it out of the tab order and stops every press, so onclick is not called. Fabricate coerces no disabled to a boolean, so only true and false are in the contract. Never pass true while the button holds focus, as Ownership and theme states. A Fabricate that predates the '20' and '22' rungs draws the default rung for each and refuses nothing, which describe cannot show; adding them is additive, and the entry stays at version 1. onclick is a required callback, called with no argument each time the button is pressed, each repeat of a held Enter key included. aria-expanded is true or false, and is an aria prop: Fabricate writes it on the button. It is for a button whose press shows and hides a region you draw, as the Button section states; the name is the same in both states, and you omit the prop on a button that does no such thing. Its glyph may follow the state: pass the other icon in the same update, as fas fa-chevron-up while the region is shown. The tooltip is ariaLabel, plain text that is never read as HTML. Fabricate writes it as data-tooltip-text on the button in every mount, and Foundry’s own hover listener shows it after a delay while the pointer rests on the button. Under keyboard focus, and only under :focus-visible, Fabricate opens the same tooltip itself through game.tooltip, which it reads when the focus arrives, and closes it on blur, a press, Escape, destroy and an update that changes ariaLabel or passes disabled: true; it closes only its own tooltip, and Escape still reaches a keydown listener of yours above target. While either tooltip is open, the one hover shows or the one keyboard focus opens, Foundry sets aria-describedby to tooltip on the button and removes it when the tooltip closes, so a screen reader may read the name a second time as its description. You cannot suppress that second reading at version 1, so keep ariaLabel a short verb phrase. description is optional final display text, the button’s accessible description, drawn and held as the Button section states: inside the button, hidden from every user and named in its aria-describedby, after tooltip while either tooltip is open, so a screen reader may read the name again and then the description, and alone once it has closed; a value that is not a string, or is blank, writes none. It is not the tooltip, which stays ariaLabel, and a disabled button keeps it. A Fabricate that predates description refuses it with "description" is not a data attribute, which describe('IconButton').props shows by leaving it out; adding it is additive, and the entry stays at version 1. Rest data-* is for your own hooks. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. They land on the button itself, so data-keyboard-focus, data-action, data-cursor, every data-tooltip name, and the two names Fabricate’s own stylesheet reads off its own buttons, data-validation-focused and data-essence-sort-direction, are refused with "<key>" is reserved on IconButton. That includes data-tooltip-text, so the tooltip says only what ariaLabel says. data-locked is refused the same way, because Foundry pins a copy of any tooltip it opens on an element carrying data-locked, and the closes this section states never reach that copy. Its face and ring come from Fabricate’s module sheet, and it is drawn the same in the Manager, the player window and, under the standalone style root, a companion’s own window or dialog. Give target display: flex and align your own content to the button by centring. The button is the only focusable element Fabricate draws in target, inside the standalone style root in a target with no Fabricate root, so target.querySelector('button') reaches it. An update keeps the same button, so focus stays on it; destroy removes it, so where it holds focus, move focus first, as Ownership and theme states. The keyboard ring is the accent, 2px wide and 2px clear of the button, so it reaches 4px beyond the button on every side; leave that much inside any edge of your own that clips. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and falls short against --fab-bg-3 in two, so mount the button on one of those four grounds. Its default rung’s side, its corner and glyph size, each role’s colours and edge beyond what this section states, the delay before Foundry shows its hover tooltip, and how Fabricate redraws an icon button in its own rows, pager and inspectors are private. A class, a tooltip of its own and content beside the glyph are refused, because a rest key must be a data-* attribute.
A worked row control follows: the remove control at the end of a row you draw inside a Fabricate window, for example in an extension target.
// After `load(['IconButton'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `IconButton` describes none: draw your own control there.
if (!fabUi?.describe?.('IconButton')) return;
const remove = fabUi.mount('IconButton', {
target, // Inside a Fabricate window, at the end of your row.
props: {
icon: 'fas fa-trash',
ariaLabel: `Delete ${reagent.name}`, // The verb and its object: the role is never announced.
role: 'ghost-danger',
size: '26',
onclick: () => acmeReagents.confirmDelete(reagent.id), // Confirm in a dialog of Foundry's.
'data-acme-reagent': reagent.id,
},
});
// `remove.destroy()` when the row goes away, moving focus first if the button holds it.
EditorTabs
EditorTabs draws the design system’s tab strip (<TabBar> in the library): a role="tablist" row of native <button type="button"> tabs, one for each item of tabs, for moving between panels you draw. It draws no panel, and on a tab no padlock, no description and no mark but the tab’s count. tabs is required and is an array of { id, label, icon, count } items, one tab each, drawn in that order. Each id is required and is an id-safe token of letters, digits, - and _, unique in the strip, as inputs; Fabricate builds ids from it and checks nothing about it. Each label is required and is final display text, the tab’s visible text and its accessible name, which a count follows; a label of white space alone leaves the tab with no name, so never pass one. Each icon is optional Font Awesome classes for a glyph drawn before the label, hidden from assistive technology. Each count is optional and is a whole number of 0 or more, as 2, drawn after the label as the strip’s record count, a small muted numeral in the mono face, on the selected tab as on any other. A tab with a count is named its label, a comma, a space and the count’s digits, as “Factions, 2”, and the numeral itself is hidden from assistive technology, so the count is read once; Fabricate adds no word, so the name reads alike in every language. A count of 0 is drawn and named, so omit count on a tab with nothing to count; a large count is drawn in full, in digits with no grouping, as 1250, and never capped, up to Number.MAX_SAFE_INTEGER, above which a count draws nothing. A count that is not a whole number from 0 to Number.MAX_SAFE_INTEGER, a numeric string such as '2', a negative, a fraction, NaN and Infinity among them, draws nothing, adds nothing to the name and is not refused. The numeral’s muted ink clears 4.5:1 on --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, on a selected, an unselected and a hovered tab alike; under forced colours it is drawn in the system text colour, and it never marks the selection. An item’s other members are private and Fabricate draws nothing from them; a function in one is refused. Naming count is additive, and EditorTabs’ version stays 1: before it count was a private member that drew nothing. A Fabricate that predates it draws no count and refuses none, and describe names no item member, so put a count a reader must have in the panel too. activeTab is the id of the selected tab and defaults to '': that tab is drawn selected, carries aria-selected="true" and is the strip’s one tab stop, with tabindex="0" where every other tab has -1; when it names no item no tab is selected and the first tab is the tab stop. onSelect is a required callback, called with one argument, the id of the tab a press or a key reaches, the selected tab’s included. The strip holds no selection: it draws a tab selected only once an update passes that id as activeTab, so make that update from inside onSelect, before any await. Until that update, focus rests on a tab drawn unselected with tabindex="-1" while the previous tab stays the tab stop; if you decline a selection, move focus back to the tab stop. ariaLabel is required and is the strip’s name, final display text, as “Reagent sections”. idStem is required and is the stem of every id the strip writes: a tab’s id is <idStem>-tab-<id>, and its aria-controls names <idStem>-panel-<id>. Fabricate builds ids from it, so make it unique in the document with your module id, as acme-reagents. Draw each panel outside target, after it in document order so Tab moves from the tab into the panel, with id="<idStem>-panel-<id>", role="tabpanel" and aria-labelledby="<idStem>-tab-<id>", and give it tabindex="0" when it holds no focusable element. activePanelOnly is true or false and defaults to false: true writes aria-controls on the selected tab alone, for a strip whose panels you draw one at a time; with false every tab writes it, so every panel it names exists in the document, or a screen reader may report the relationship as broken. The strip is horizontal and selects as focus moves: ArrowRight and ArrowLeft move focus to the next and the previous tab, wrapping at either end, Home to the first and End to the last, and then call onSelect with the id of the tab focus reached. Those four keys have their default prevented and still bubble to a keydown listener of yours above target; the strip handles no other key, so ArrowUp and ArrowDown move nothing, and Enter and Space press the focused tab as a native button does. A key pressed with Alt, Ctrl or Meta held is left to the platform, so Alt+ArrowLeft still goes back where the browser binds it. A press, by pointer, Enter or Space, focuses its tab and then calls onSelect. Focus moves only among the strip’s tabs, on a press and on those four keys, and never out of target. To return focus to the strip, focus target.querySelector('[role="tab"][tabindex="0"]'), the strip’s one tab stop: the selected tab, or the first tab when activeTab names none. An update keeps every tab whose id it keeps, so focus stays on it; one that drops the focused tab’s item, and destroy, remove that tab, so where it holds focus, move focus first, as Ownership and theme states. The strip adds no listener of its own to the document and stops the propagation of no key, so wherever the pointer rests, Escape reaches your keydown listeners on its path, the document’s among them. Rest data-* is for your own hooks, and lands on the tablist, never on a tab. Name them for your module, as data-<module-id>-…; a name Fabricate writes is private. Its row, its tabs and their ring come from Fabricate’s module sheet, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. The row wraps onto a further row when target is narrower than its tabs. An empty tabs draws the named tablist with no tab, so pass at least one item where the strip must be reachable. The keyboard ring is the accent, 2px wide and 2px clear of the tab, so it reaches 4px beyond the tab on every side; leave that much inside any edge of your own that clips. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and falls short against --fab-bg-3 in two, so mount the strip on one of those four grounds. Under forced colours the reader’s colours repaint every tab’s border in the text colour, so the selected tab’s indicator is drawn in Highlight and 4px thick against the others’ 2px, in a box of the same height, and the selected tab is told from the others by that indicator and not by its weight. Its padding, rule, type and colour figures beyond what this section states, and how Fabricate draws a tab strip in its own editors, are private. badges, annotated, danger, a class and Fabricate’s own hook and id-stem props are refused, because a rest key must be a data-* attribute, so a tab draws no mark but its count, no padlock and no description, and takes no name but its label and its count.
A worked strip follows: two sections of a reagent sheet you draw inside a Fabricate window, for example in an extension target, with one panel shown at a time.
// After `load(['EditorTabs'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `EditorTabs` describes none: draw your own strip there.
if (!fabUi?.describe?.('EditorTabs')) return;
const sections = [
{ id: 'inputs', label: 'Inputs', icon: 'fas fa-flask' },
{ id: 'outputs', label: 'Outputs', icon: 'fas fa-box-open' },
];
let shown = 'inputs';
const props = () => ({
tabs: sections,
activeTab: shown,
ariaLabel: 'Reagent sections',
// Your panels, after `target`: id="acme-reagents-panel-<id>", role="tabpanel",
// aria-labelledby="acme-reagents-tab-<id>", and tabindex="0" where one holds no control.
idStem: 'acme-reagents',
activePanelOnly: true,
onSelect: (id) => {
shown = id;
strip.update(props()); // Before any `await`, so the tab is drawn selected at once.
acmeReagents.showPanel(id);
},
});
const strip = fabUi.mount('EditorTabs', { target, props: props() });
// `strip.destroy()` when the sheet goes away, moving focus first if a tab holds it.
RadioCardGroup
RadioCardGroup draws the design system’s option cards (<OptionCards> in the library): a named <fieldset> of cards, one for each item of options, each holding a native <input type="radio">, for one choice among a few options. options is required and is an array of { value, label, description, example, badge, icon } items, one card each, drawn in that order. Each value is required and is a non-empty string, unique in the group; a list with a duplicate is unsupported and how it draws is private. Each label is required and is final display text, the radio’s whole name; a label of white space alone leaves the radio with no name, so never pass one. Each description is optional final display text drawn beneath the label, which describes the radio. Each example is optional final display text drawn as a third line beneath the description, which describes the radio. Each badge is optional and is { label, tone }: label is final display text drawn in a chip beside the label, which describes the radio and never joins its name, and a badge whose label is not a non-empty string draws none. A badge’s tone is optional and is 'positive', 'warning', 'info', 'danger', 'accent' or 'secondary', the chip’s colour family; any other value draws 'secondary'. A radio’s description reads its badge, description, example, reason and option body in that order, whichever render. A badge’s ink clears 4.5:1 on a card’s rest ground and on a chosen card’s in every palette, and a disabled option dims its badge with its label. Each icon is optional Font Awesome classes for a glyph drawn in a chip, hidden from assistive technology. An item’s other members, and a badge’s, are private and Fabricate draws nothing from them; a function in one is refused. Naming example and badge is additive, and RadioCardGroup’s version stays 1: before them both were private members that drew nothing. A Fabricate that predates them draws neither and refuses neither, and describe names no item member, so put text a reader must have in label or description too. value is the chosen option’s value and defaults to '': that option’s card is drawn chosen and its radio checked, and a value that names no option leaves no card chosen. onChange is a required callback, called with one argument, the chosen option’s value, a string, when a press or a key checks a radio; it is never called for a disabled option or a disabled group, and a press on the chosen card calls nothing, because a checked radio fires no change. When onChange returns, or throws, Fabricate checks the radio of the mount’s value again, so to accept a choice make the update that passes it from inside onChange, before any await, and the new card is drawn chosen; a choice you decline leaves the previous card chosen. legend is required and is the fieldset’s name, final display text drawn visually hidden; a legend of white space alone leaves the fieldset with no name, so never pass one. layout is 'row' or 'stacked' and defaults to 'row': the chip beside a card’s text, or above it. columns is 1, 2 or 3 and defaults to 2, the cards’ tracks per row; any other value is private. disabled is true or false and defaults to false: true disables every radio natively. disabledOptions is an array of { value, reason } items, each disabling the option it names, and reason is required non-empty final display text drawn beneath the option’s description inside its card, never dimmed, and added to the radio’s aria-describedby. An item that names no option is ignored, and where a value is named twice the first non-empty reason wins. activation is 'automatic' or 'manual' and defaults to 'automatic': whether a key that moves focus also chooses. Only the exact string 'manual' draws a manual group, and any other value, 'Manual' and true among them, draws an automatic one. columns, layout, disabled and disabledOptions draw and disable the same under either. A Fabricate that predates activation refuses it with "activation" is not a data attribute, and describe('RadioCardGroup').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. In an automatic group each control is a native radio, so the group consumes no key itself: the platform’s radio group moves focus to the next or the previous enabled radio on the arrow keys, wrapping at either end and skipping a disabled one, and checks it, and Space checks the focused radio. Each such check fires change, which calls onChange, and every key still bubbles to a keydown listener of yours above target. In a manual group the arrow keys, Home and End move focus and choose nothing, so a companion that writes a persisted setting on each choice is told of a choice only when the user makes one. Fabricate prevents those keys’ default and moves focus itself: ArrowDown and ArrowRight to the next enabled radio, ArrowUp and ArrowLeft to the previous one, wrapping at either end and skipping a disabled one, ArrowLeft and ArrowRight swapped where the radios’ direction is rtl, and Home and End to the first and last enabled radio. Space checks the focused radio, as the platform does, and Enter is held from the platform and checks it too, once per press and never on a held key’s repeat, so either, or a press, calls onChange once with its value, and neither calls anything on the checked radio. A key held with Alt, Ctrl or Meta, and every other key, is the platform’s, and every key still bubbles to a keydown listener of yours above target. This departs from the WAI-ARIA radio group pattern, where an arrow key checks the radio it reaches: the radios keep the native roles, so Chromium’s accessibility tree has a group named by the legend holding radios named by their labels, and the radio an arrow key reaches is focused and states checked false until Space or Enter chooses it, which is what a screen reader is given to announce; no screen reader was tested. The focused radio’s keyboard ring and the chosen card’s 4px radio edge, accent border and ground are different shapes, so focus on an unchosen card is told from the choice without colour, and both shapes hold under forced colours. Focus moves only among one group’s radios, by the platform’s own handling or, in a manual group, Fabricate’s, and never out of target. Tab reaches either group at the platform’s stop: in Chromium the checked radio, or with none checked the first enabled radio and later the one focus last left; in a manual group Chromium’s Shift+Tab from a radio an arrow key reached stops on the checked radio before it leaves the group. This key handling was measured in Chromium alone: that preventing an arrow key’s default also stops Firefox and Safari checking the radio, and where their Tab stops fall, is untested. To return focus to the group, focus target.querySelector('input[type="radio"]:checked'), or the first enabled radio when no option is chosen. After a key, a declined choice leaves focus on the radio the key reached, drawn unchecked, so move focus to target.querySelector('input[type="radio"]:checked') after you decline one. In a host that replaces its content on render (a DialogV2, a Handlebars part, or a submitOnChange sheet that renders again after the update a choice causes) the radios are new elements after every render: note in _preRender whether focus was inside target and, after mounting again in _onRender, focus target.querySelector('input[type="radio"]:checked'), or the first enabled radio when none is checked. An update that sets disabled, or names the focused radio’s option in disabledOptions, disables the radio holding focus, and the platform moves focus to the document body, where Foundry’s keybindings hear Escape and the arrow keys, so move focus first. Each choice fires a bubbling change, so a form with submitOnChange submits on every choice. The radios carry a private name, unique to the mount, so the chosen value appears under that name in a form’s data, except while the group is disabled, and a document sheet’s schema discards the key: read the choice from onChange, never from the form. An automatic group consumes no key, so where the platform applies implicit submission to a focused radio, Enter submits the <form> it is in; mount it in no form whose submit you do not want, or make it manual, whose Enter submits nothing. Rest data-* attributes land on the fieldset, never on a card or a radio. Its cards, chips and radios come from Fabricate’s module sheet, rooted at .fabricate-option-cards, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. It reflows to fewer tracks only under a Fabricate host that names fabricate-option-host, a name you give no element, so under the standalone style root it never reflows and you choose columns for the width of target; when and how it reflows is private. An empty options draws the named fieldset with no card and no radio, so nothing inside target takes focus; pass at least one option where the group must be reachable. The radio’s keyboard ring is the accent, 2px wide and 2px clear, drawn on the card’s own ground. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, and against a chosen card’s --fab-surface-soft over --fab-bg-2, in every palette, and falls short against --fab-bg-3 in two, so mount the group on one of those four grounds. groupName, cardId, hint, legendVisible, optionDataAttr, optionBody and a class are refused, because a rest key must be a data-* attribute, so the group never draws a hint, a visible legend or content of your own in a card.
A worked group follows: a breakage choice on a tool sheet you draw inside a Fabricate window, for example in an extension target.
// After `load(['RadioCardGroup'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `RadioCardGroup` describes none: draw your own choice there.
if (!fabUi?.describe?.('RadioCardGroup')) return;
let chosen = 'breakable';
const props = () => ({
legend: 'When the tool breaks',
options: [
{ value: 'breakable', label: 'Breakable', icon: 'fas fa-hammer' },
{ value: 'immune', label: 'Immune', description: 'It never breaks.', icon: 'fas fa-lock' },
{ value: 'limited', label: 'Limited uses', icon: 'fas fa-hourglass-half' },
],
value: chosen,
disabledOptions: [{ value: 'limited', reason: 'Coming soon' }],
onChange: (value) => {
chosen = value;
group.update(props()); // Before any `await`, so the card is drawn chosen at once.
acmeTools.saveBreakage(value);
},
});
const group = fabUi.mount('RadioCardGroup', { target, props: props() });
// `group.destroy()` when the sheet goes away, moving focus first if a radio holds it.
SegmentedControl
SegmentedControl draws the design system’s segmented control (<Segmented> in the library): a role="radiogroup" track of native radios, each behind a label segment, one for each item of options, drawn in that order. options is required and is an array of { value, label, ariaLabel, title, icon, variant, disabled } items. value is required, a string or a number, unique in the control; a list with a duplicate is unsupported and how it draws is private. label is required and is final display text, the segment’s whole visible text and its radio’s accessible name; a label of white space alone leaves the radio with no name, so never pass one. ariaLabel is optional final display text, the option’s accessible name in place of label, for state the segment shows by its look alone, such as who chose it; the radio states its own checked state, so leave that out. Fabricate writes a non-blank string as the radio’s aria-label, and writes none for a blank string or any other value, so label names the radio. It must contain label’s words as one run of whole words, as Button’s ariaLabel must contain its label, so a speech-input user who says the words they see reaches the option (WCAG 2.2 success criterion 2.5.3); a numeric label is held as its digits. A mount or update holding an option whose non-blank ariaLabel does not contain it throws "options[<index>].ariaLabel" must contain the text of "options[<index>].label" ("<label>" is not in "<name>"), naming the first such option, and an update leaves the earlier props drawn. Build it by inserting the label string itself, as format('{label}, chosen by {name}', { label, name }) with a format of your own, and put the label first where the language allows. Chromium’s own accessibility tree names each radio by its ariaLabel, or by its label without one, and Playwright’s accessibility snapshot of the focused radio shows that name as the arrow keys reach it; no screen reader was tested. title is optional text, final display text, a hint about the option; Fabricate writes it as the segment’s data-tooltip-text, never as a native title, so Foundry’s own hover listener shows it as plain text, never read as HTML, after a delay while the pointer rests on the segment. It is never the radio’s accessible name, which stays label, and it changes nothing about the radiogroup’s roles, states or keys. Fabricate also writes it as the radio’s accessible description: the radio carries aria-describedby naming a hidden node outside the label that holds the hint, with an id built from the mount and the option’s position. A screen reader is meant to announce the hint after the name, so a keyboard, touch or screen-reader user reaches it. Chromium’s own accessibility tree gives each hinted radio the hint as its description and leaves its name as it was, and no screen reader was tested. Fabricate opens no tooltip under keyboard focus, so a sighted keyboard or touch user is not shown it: a hint such a user needs goes in label or in text beside the control. A Fabricate that predates the description gives the hint to the pointer only. A title that is not a string, or is white space alone, draws no tooltip and no description. icon is optional Font Awesome classes for a glyph drawn before the label, hidden from assistive technology. variant is optional and is 'info', which draws that option’s segment in the info tint while it is the selected one, in a control with no tone or with an 'accent' or 'accent-soft' one; under tone: 'info' the selected segment is solid info either way, and any other value is private. disabled: true disables that option’s radio natively, so the arrow keys skip it and it never calls onChange. An item’s other members are private, so pass none; a function in one is refused. Among them count and badge draw a tally beside the label that an ariaLabel, as the radio’s name, leaves out; publishing either later holds ariaLabel to containing it too, or adds it to the name. value is the value of the selected option and defaults to ''. It is compared with ===, so '10' selects no option whose value is 10, and a value that names no option leaves no segment selected. onChange is a required callback, called with one argument, the value of the option a press or a key reaches; a press on the selected segment calls nothing, because a checked radio fires no change. The control holds no selection: it draws a segment selected only once an update passes that option’s value, so make that update from inside onChange, before any await. The platform checks the reached radio first; when onChange returns, Fabricate sets the check back on the radio of value, inside that same change, so a declined change leaves the previous radio checked. Focus stays on the reached radio, drawn unchecked, so after you decline a change move focus to target.querySelector('input[type="radio"]:checked'). ariaLabel is required and is the radiogroup’s name, final display text. fill is true or false and defaults to false: true stretches the track across target and gives every segment an equal share. density is 'default', 'compact', 'field' or 'inline' and defaults to 'default'; any other value is private. 'compact' and 'field' draw the track on the --fab-bg-1 fill, with smaller segments in a looser well, each taking an equal share, and 'field' also edges the selected segment in the accent border. Neither sets the height of a card or panel you draw around the control, so size that yourself. tone is 'accent', 'accent-soft' or 'info' and defaults to none: 'accent' fills the selected segment solid in the accent and 'info' in the info colour, each leaving the other segments bare, and 'accent-soft' tints it softly in the accent; any other value is private. An 'accent' or 'accent-soft' control draws such an option in the info tint, not in its own. shape is 'pill' or absent: 'pill' draws the segments as separate pills, with no fill, edge or padding on the track; any other value is private. surface is 'default' or 'panel' and defaults to 'default': 'panel' fills the track with --fab-bg-0, one step below a --fab-bg-1 panel, under every density, tone and size, and changes no segment, height or ring. The 'pill' shape draws no track fill, so 'panel' draws nothing there. Any other value, 'Panel', true and 'false' among them, draws the default track. size is 34 or '34', a number or its string, and defaults to none: 34 draws the track 34px tall, its border included, and stretches each segment to fill it inside the density’s padding, so the control lines up with a 34px Field or Button beside it; any other value, 35 and '34px' among them, draws the density’s own height. Without size the 'inline' density draws a 30px track and 'compact' and 'field' a 36px one, and the 'default' density’s height follows the type size and is private; the 'pill' shape drops the track’s padding, so it draws 'inline' at 26px and 'compact' and 'field' at 28px, and size: 34 still draws 34px there. Naming density’s 'compact' and 'field' values and an option’s title is additive, and SegmentedControl’s version stays 1: no key is new, so no Fabricate refuses either. A Fabricate that predates them draws a 'compact' or 'field' density as it does now, without having promised it, and ignores a title, and describe names the same props before and after, so require the Fabricate release that publishes them if you rely on either. Naming tone, shape and an option’s variant is additive, and SegmentedControl’s version stays 1: before them tone and shape were refused as rest keys and variant was private. A Fabricate that predates them refuses tone and shape, and describe names them only once the running Fabricate publishes them, so read describe('SegmentedControl') before you pass either. A describe that names tone is from a Fabricate that keeps a variant’s tint in an accent track. Naming surface, size and an option’s ariaLabel is additive, and SegmentedControl’s version stays 1: a Fabricate that predates them refuses surface and size with "<key>" is not a data attribute, and names each radio by its label whatever its option’s ariaLabel, so read describe('SegmentedControl').props.surface before you pass any of the three. The radios share one name Fabricate makes unique to the mount, so two controls never uncheck each other. Fabricate handles and stops no key: the platform moves focus and the check to the next or previous enabled radio on the arrow keys, wrapping, and Space checks the focused radio, each check calling onChange. Focus moves only among one control’s radios and never out of target. To return focus to the control, focus target.querySelector('input[type="radio"]:checked'), or the first enabled radio when no option is selected. A pointer press on a segment bubbles two clicks, the label’s and the one it forwards to the radio, and an arrow key may bubble one from the radio it reaches; count choices from onChange, never from click. An update keeps every radio whose option it keeps, so focus stays on it; one that drops the focused radio’s option, and destroy, take focus from it, and one that disables it moves focus to <body>, where Foundry’s keybindings hear Escape and the arrow keys, so move focus first. In a host that replaces its content on render (DialogV2, a Handlebars part, a submitOnChange sheet that re-renders after the update a change causes) the radios are new elements after every render: note in _preRender whether focus was inside target and, after mounting again in _onRender, focus the checked radio, or the first enabled one. Each change fires a bubbling change, so a form with submitOnChange submits on every change and reads its data inside that change, after Fabricate has set the check from value. The radios carry a private name that a document sheet’s schema discards, and a form carries the value as a string: Foundry’s FormDataExtended carries the checked radio’s value even while that radio is disabled, as long as another radio of the control is enabled, and a native FormData omits a disabled radio; read the choice from onChange, never from the form. Where the browser’s implicit submission covers a focused radio, Enter submits the form through its first submit button, which in DialogV2.confirm is Yes, so mount the control in no form whose submit you do not want. Rest data-* attributes land on the radiogroup, never on a segment or a radio. It is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. An empty options draws the named radiogroup with no segment and no radio, so nothing inside target takes focus; pass at least one option where the control must be reachable. The keyboard ring is the accent, 2px wide and 2px clear of the segment, so it reaches 4px beyond the segment and 1px beyond the track’s outer edge, or 3px in the 'pill' shape; leave room for it inside any edge of your own that clips. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, against the track’s fill over each, and against the selected segment’s fill over the track’s or, in the 'pill' shape, over the ground, in every palette but for the solid fill of the 'accent' and 'info' tones, and falls short against --fab-bg-3 in two, so mount the control on one of those four grounds. With tone 'accent' or 'info' the ring is not guaranteed against the solid fill of a neighbouring selected segment, which it falls short of in every palette. On a 'compact' or 'field' track the ring reaches the track’s inner edge and no further, so it is drawn over the track’s --fab-bg-1 fill alone. The selected state is carried by weight alone under forced colors, in every density, and no test checks forced colors beyond that weight, and by nothing in the 'pill' shape. On the 'panel' track the idle ink, at rest and under the pointer, and the selected segment’s ink on its fill, under no tone and each published tone and variant, clear 4.5:1 in every palette, and the ring clears 3:1 on the track; the track is opaque, so this holds on any of the four grounds, but on --fab-bg-0 it draws no step below its ground, so mount it on one of the other three. The selected segment’s edge, drawn over its own fill, measures 2.09 to 2.86:1 against the 'panel' track, its fill 1.23 to 1.38:1, and its --fab-text ink 1.89 to 2.79:1 against the idle segments’ --fab-text-muted, across the seven palettes. Under forced colors the segments’ edges, fills and inks are all system colours, so weight alone (600 against 500) carries the selected state, as on the default track. groupName, iconOnly, optionDataAttr and a class are refused, because a rest key must be a data-* attribute, so the control never draws an icon-only run or a hook of yours on a segment.
A worked control follows: an ingredient filter on a panel you draw inside a Fabricate window, for example in an extension target.
// After `load(['SegmentedControl'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `SegmentedControl` describes none: draw your own control there.
if (!fabUi?.describe?.('SegmentedControl')) return;
let filter = 'all';
const props = () => ({
ariaLabel: 'Ingredient filter',
options: [
{ value: 'all', label: 'All' },
{ value: 'owned', label: 'Owned', icon: 'fas fa-check' },
{ value: 'missing', label: 'Missing', icon: 'fas fa-xmark' },
],
value: filter,
onChange: (value) => {
filter = value;
control.update(props()); // Before any `await`, so the segment is drawn selected at once.
acmeIngredients.applyFilter(value);
},
});
const control = fabUi.mount('SegmentedControl', { target, props: props() });
// `control.destroy()` when the panel goes away, moving focus first if a radio holds it.
Pagination
Pagination draws the design system’s pager (<Pagination> in the library): a named region holding a range summary, a named navigation of two arrow buttons around a page-position label, and a page-size control, for a list you draw a page at a time. It holds no page: it draws the window totalCount, pageSize and pageIndex describe, and you draw the rows. totalCount is required and is the number of records in the whole list, a whole number of 0 or more. pageSize is required and is the number of records on a page, a whole number of 1 or more. pageIndex is the zero-based index of the page shown and defaults to 0. The page count is totalCount divided by pageSize, rounded up, and never less than 1, and you keep pageIndex below it. pageSizeOptions is required and is an array of whole numbers of 1 or more, the sizes offered. The page-size control offers the sorted union of pageSizeOptions and pageSize, each once, and is not drawn, caption included, while that union holds fewer than two sizes, so [] draws none. Each size’s segment and radio are named by its numeral, the number in digits with no grouping. onPageChange is a required callback, called with one argument, the zero-based index of the page an arrow press reaches. The Previous arrow is disabled on the first page and the Next arrow on the last, and a disabled arrow calls nothing. The pager draws a page only once an update passes its index as pageIndex, so a second press before that update reports the same index again, and a call you decline leaves the page drawn as it was. onPageSizeChange is a required callback, called with one argument, the size, a number, of the segment a press or a key reaches; a press on the selected size calls nothing. The page-size control is a SegmentedControl, so make the update that passes the new pageSize, and the pageIndex you keep for that size, from inside onPageSizeChange, before any await. A size you decline leaves the previous size’s radio checked, and focus on the radio the key reached, drawn unchecked. persistent is true or false and defaults to false. With true the pager is always drawn, and an arrow that leads nowhere is disabled. With false the pager is drawn only while totalCount is greater than the smallest of pageSize and pageSizeOptions, and its navigation only while there is more than one page; otherwise it draws nothing, so target is empty under a Fabricate root and holds only the empty standalone style root elsewhere, and nothing inside it takes focus. While focus is inside the pager it stays drawn, and it is removed once focus leaves it. density is 'default' or 'compact' and defaults to 'default'; any other value is private. 'default' draws the bar on its own --fab-bg-1 fill. 'compact' draws one transparent row whose page-position label is visually hidden and stays in the accessibility tree, and whose page-size control takes SegmentedControl’s inline rung. ariaLabel and navLabel are required and are the region’s name and the navigation’s name, each final display text. Two pagers on one screen take distinct names, because a screen-reader user moves between landmarks by name. landmarks is 'both' or 'nav' and defaults to 'both'; a value outside the set draws 'both', and nothing is coerced. 'both' draws the pager as a region named by ariaLabel holding a navigation named by navLabel, two landmarks. 'nav' draws the same pager with no region, so its navigation, named by navLabel, is its one landmark, for a screen showing several paged lists. ariaLabel is still required there, and an empty one throws Pagination requires a non-empty "ariaLabel", though it names nothing; pass the list’s name, as “Recipes”, so the pager still reads sensibly if a later update draws 'both'. While the navigation is not drawn, as on a single page without persistent, a 'nav' pager adds no landmark. Give each such pager’s navLabel the name of its list, as “Recipe pages”, because that is then the only name a screen-reader user moves between. previousLabel and nextLabel are required and are the arrows’ names, final display text. Each arrow’s name is also its tooltip, shown on hover and under keyboard focus as the IconButton section states, the focus Fabricate moves included. perPageLabel is required and is the page-size caption, final display text drawn visibly before the control, which names its radiogroup. A name or caption of white space alone leaves its element with no name, so never pass one. perPageAriaLabel is optional final display text naming the page-size radiogroup in place of the caption, which is still drawn, as “Per page, recipes”, so the groups of several pagers take distinct names; a value that is not a string, or is blank, names none, and the caption names the group. It must contain perPageLabel’s words as one run of whole words, a number by its digits, compared as Button’s ariaLabel is (WCAG 2.2 success criterion 2.5.3), and a mount or update whose non-blank perPageAriaLabel does not throws "perPageAriaLabel" must contain the text of "perPageLabel" ("<caption>" is not in "<name>"); build it by inserting the caption string itself, as `${perPageLabel}, recipes`. A Fabricate that predates landmarks and perPageAriaLabel refuses each with "<key>" is not a prop of Pagination, which describe('Pagination').props shows by leaving it out; adding them is additive, and the entry stays at version 1. rangeTemplate is required and is the summary’s template, final display text in which Fabricate replaces {first}, {last} and {total} with the first and last record shown and totalCount, as “{first}–{last} of {total} reagents”; with no record shown, {first} and {last} are both 0. pageTemplate is required and is the page-position template, in which Fabricate replaces {page} with the one-based page shown and {total} with the page count, as “Page {page} of {total}”. Fabricate fills each placeholder of either template with the number in digits, leaves any other {name} as written and changes nothing else, so you choose each template’s wording, its plural form included, from the totalCount you pass. Each arrow is a native <button type="button">, so Enter and Space press it, and the page-size radios take the keys SegmentedControl’s section states; Fabricate stops no key, and cancels only a held Enter’s repeats on the arrow or page-size radio it moved focus to, as the next paragraph states. Focus moves only as the page-size control’s section states, except that when an update disables or removes the arrow holding focus, and focus has not moved elsewhere meanwhile, Fabricate moves focus to the other arrow while it is enabled, and otherwise to the checked page-size radio while one is drawn. So a keyboard user who presses Next onto the last page rests on Previous. On the arrow or page-size radio it moved focus to, Fabricate cancels the repeats of an Enter still held from that press until that key is released or Enter is pressed again, so a held Enter stops on the end page rather than walking back. With neither to move to, Fabricate takes focus off the arrow, so focus is on the document body, where Foundry’s keybindings hear Escape, and a pager that only focus kept drawn is removed; when you make that update, move focus first. To return focus to the pager, focus target.querySelector('button:not(:disabled), input[type="radio"]:checked'): the first enabled arrow, else the checked size. An arrow press bubbles one click, and the page-size control’s clicks are as its section states, so count page turns from onPageChange, never from click. An arrow submits no <form>. A size choice fires a bubbling change as SegmentedControl’s section states, so a form with submitOnChange submits on it; read the size from onPageSizeChange, never from the form. It takes no rest keys, so a data-* key is refused, and so are showPageSize, multiPageOnly, edge and a class. Its bar, arrows and ring come from Fabricate’s module sheet, rooted at .fabricate-pagination, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. The arrows’ keyboard ring is the accent, 2px wide and 2px clear of the arrow, so it reaches 4px beyond the arrow, and the page-size control’s ring reaches as SegmentedControl’s section states. The ring clears 3:1 against the default bar’s --fab-bg-1 and, under 'compact', against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, in every palette, and falls short against --fab-bg-3 in two, so mount a compact pager on one of those four grounds and leave room for the ring inside any edge of your own that clips.
A worked pager follows: a reagent list you draw a page at a time on a panel inside a Fabricate window, for example in an extension target.
// After `load(['Pagination'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates `Pagination` describes none: draw your own pager there.
if (!fabUi?.describe?.('Pagination')) return;
let pageIndex = 0;
let pageSize = 25;
const props = () => ({
totalCount: acmeReagents.count(),
pageSize,
pageIndex,
pageSizeOptions: [10, 25, 50],
ariaLabel: 'Reagent pages',
navLabel: 'Reagent page navigation',
previousLabel: 'Previous reagents page',
nextLabel: 'Next reagents page',
perPageLabel: 'Per page',
rangeTemplate:
acmeReagents.count() === 1
? '{first}–{last} of {total} reagent'
: '{first}–{last} of {total} reagents',
pageTemplate: 'Page {page} of {total}',
onPageChange: (index) => {
pageIndex = index;
pager.update(props()); // Before any `await`, so the summary and arrows move at once.
acmeReagents.showPage(pageIndex, pageSize);
},
onPageSizeChange: async (size) => {
pageSize = size;
pageIndex = 0;
pager.update(props()); // Before any `await`, so the chosen size stays checked.
await acmeReagents.showPage(pageIndex, pageSize);
},
});
const pager = fabUi.mount('Pagination', { target, props: props() });
// `pager.destroy()` when the panel goes away, moving focus first if the pager holds it.
IconPicker
IconPicker draws Fabricate’s icon picker: a <button> trigger showing a glyph, its name and a caret, which opens a list of Fabricate’s icon vocabulary with a query field, in an overlay, for one glyph that commits as it is chosen. The trigger fills the width of target, so size target yourself; an icon-only trigger is sized to its glyph instead, as iconOnly states. The trigger is the only focusable element inside target, so to return focus to the picker, focus target.querySelector('button'). The list offers the vocabulary game.fabricate.listCuratedIcons() answers on the same client, described under Icon Vocabulary, one solid-weight row per glyph, in that vocabulary’s order while the query is empty. Each row is named by its glyph’s label, as game.fabricate.listCuratedIcons() answers it on the same client, which is English and is not localized. The trigger shows that same name beside the glyph, as its caption. value is the chosen glyph’s Font Awesome class string, a weight token then fa-<name>, as 'fas fa-gear', and its iconCode or any of its aliases selects its row. With an empty query, the row for value is pinned first and marked selected. With value absent, '', or carrying no fa-<name> token, the trigger draws a default glyph, which is private. A value whose <name> the vocabulary lists under no name or alias is drawn on the trigger as written and, with an empty query, pinned as a row of its own, named by an English label Fabricate makes from <name>, which is not localized. onChange is a required callback, called with one argument, the chosen row’s class string, each time the user chooses a row by pointer or by Enter, the selected row included: fas fa-<iconCode> for a row the vocabulary lists, and for a row of its own the value’s weight token and fa-<name>. It is not called by mount, update, opening or closing the list, a query, Escape or an outside press. The picker changes nothing itself: the trigger shows the new glyph when your update passes it as value, so to refuse a choice, pass value unchanged. ariaLabel is required final display text naming what the picker chooses, as “Reagent icon”. The trigger’s name is ariaLabel, less any spacing, :, ;, ,, . or - that ends it, then a comma and a space, then the caption it draws, as “Reagent icon, Flask” from “Reagent icon” or “Reagent icon:”, so it always holds its visible label (WCAG 2.2 success criterion 2.5.3) and the choice is heard, and you never rebuild Fabricate’s caption, a stored glyph’s outside the vocabulary included. Where ariaLabel already holds the caption’s words as one run of whole words, compared as Button’s ariaLabel is held to its label, the name is ariaLabel alone, so “Reagent icon: Flask” names the trigger with the caption once; nothing is refused, as the comparison only chooses the name. The caption is the glyph’s English label, which is not localized, so a name in another language holds that English label as the caption it draws does. The name is also the trigger’s native tooltip, so a caption an ellipsis cuts in a narrow target reads whole under the pointer. listLabel is required and names the list and its dialog. searchLabel is required and names the query field. searchPlaceholder is optional hint text the empty field shows while it does not hold focus, which is not its name; the list opens with the field focused, so it is hidden until focus leaves the field, and absent, the field shows none. noMatchesText is required and is the line the list draws in place of its rows when a query matches no glyph. Never pass a name of white space alone, which leaves its element with no name. tint is optional and is one of Avatar’s tint keys, sage, mist, lavender, rose, peach, butter, aqua, mauve, ember, verdant, azure, bone and slate, a string: it recolours the trigger’s glyph alone in that --fab-tag-* colour, as a record’s own tint, and leaves the tile, the name, the caret and the list’s rows as they are. Absent, or any other value, '--fab-tag-rose', 'Rose' and ' rose' among them, draws the glyph in the default accent, and nothing is coerced. The glyph is hidden from assistive technology and the tint is colour alone, so say what the tint means in text of your own where it matters. Each tint’s glyph clears the 3:1 non-text floor on its tile over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette but mauve and slate on --fab-bg-2 in foundry-native, at 2.55:1 and 2.57:1, and the untinted glyph clears it on all four in every palette; a captioned trigger names the glyph in text beside it, so there the glyph is never the only carrier of the choice. A Fabricate that predates tint refuses it with "tint" is not a prop of IconPicker, which describe('IconPicker').props shows by leaving it out; adding it is additive, and the entry stays at version 1. iconOnly is optional, and only true draws the icon-only trigger, for a narrow column beside art of your own: the glyph’s tile alone, a square with no caption and no caret, sized to the tile rather than to target and drawn at the start of target; any other value, 'true' and 1 among them, draws the captioned trigger, and nothing is coerced. An icon-only trigger draws no text, so its name and its native tooltip are ariaLabel alone, saying what the picker chooses, as “Faction icon”. The choice is exposed as the trigger’s accessible description: aria-describedby names the chosen glyph’s caption, as “Crown”, in every mount, and names nothing while value holds no glyph, so ariaLabel need not carry the choice. Its glyph is then the only visible carrier of the choice, and in foundry-native a glyph tinted mauve or slate may be hard to see on --fab-bg-2, at 2.55:1 and 2.57:1 against the 3:1 non-text floor; whether art of your own beside it shows the same glyph again is yours to decide. It is a pointer target at least 24 by 24 CSS pixels (WCAG 2.2 success criterion 2.5.8), and its fill, keyboard ring, keys, list, aria-haspopup and aria-expanded are the captioned trigger’s, so it opens, closes and takes focus back as this section states; under forced colours its edge, glyph and ring are drawn in system colours. A Fabricate that predates iconOnly refuses it with "iconOnly" is not a prop of IconPicker, which describe('IconPicker').props shows by leaving it out, and one that predates the composed name names a captioned trigger by ariaLabel alone; adding both is additive, and the entry stays at version 1. The two arrived together, so 'iconOnly' in describe('IconPicker').props tells you the trigger’s name holds its caption; where it is false, put the caption in ariaLabel yourself.
- A press on the trigger, by pointer, Enter or Space, opens the list, and a second press closes it.
- When the list opens, focus moves into its query field, outside
target. - Typing narrows the rows to the glyphs the query matches, and an empty query lists them all; which glyphs a query matches and their order are private.
- ArrowDown and ArrowUp move the active row, which the field names with
aria-activedescendant, and Home and End do so only from the caret’s edge; Enter chooses the active row, and with no active row does nothing. - A choice closes the list and returns focus to the trigger.
- Escape in the query field closes the list without choosing and returns focus to the trigger before the key reaches Foundry, so Foundry’s dismiss keybinding closes no window; an open ApplicationV1
Dialogstill closes, as Interactive components states. - A press outside the open list closes it without choosing anything, and focus goes where the press puts it: to the element you pressed when it, or an element around it, takes focus, and otherwise to the page. With focus on the page, the next Escape reaches Foundry, which asks every open window to close.
- Tab in the query field closes the list without calling
onChange, moves focus to the trigger and leaves the browser to move it on from there, so focus lands where it would if the list were drawn just after the trigger; Shift+Tab there closes the list and returns focus to the trigger. - The list also closes without choosing, moving no focus, once focus moves to an element outside the trigger and the list; focus leaving the browser window, or moving between the main window and a detached one, closes nothing.
- The trigger stops the propagation of every key but Tab, with or without Shift, pressed while it holds focus, and of its own
click, and the open list stops everyclickinside it, so your listener abovetargetor on theoverlayHosthears Tab and no other key; while the trigger holds focus Escape closes no window, an open ApplicationV1Dialogincluded. - In a DialogV2, Escape on the trigger does not close the dialog; handle Escape in your own listener on the trigger or move focus first.
- Every key pressed in the query field, Escape included, may reach your listener on the
overlayHostor above it. - The no-match line is a polite live region, so it is announced when a query empties the list; the picker announces nothing else.
The list is the component’s overlay, so describe('IconPicker').overlays is true, and it is drawn in the host Overlays picks when it opens. Pass an overlayHost inside the same Fabricate window, or none, because the list’s rows, ring and hidden live region are drawn only under a .fabricate ancestor, and in no <form>, because Enter in the query field with no active row can submit a form it sits in; in your own window or dialog pass none, and the list opens on the standalone layer. The list opens against the trigger, and its placement inside the host is private. IconPicker takes no rest props, so a data-* prop is refused with "<key>" is not a prop of IconPicker. Its trigger, rows and marks come from Fabricate’s module sheet, rooted at .fabricate-icon-picker and .fabricate-icon-picker-popover, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, its open list on the standalone layer there. The trigger’s keyboard ring is the window’s accent ring, 2px wide and 2px clear of the trigger, and the query field shows focus by turning its own 1px border to the accent, drawn inside its box, with no ring. The ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, so mount the picker on one of those grounds and leave room for the ring inside any edge of your own that clips. An update keeps the trigger, so focus stays on it, and an update while the list is open redraws the selection in place; destroy removes the trigger and closes the list, so where the trigger or the query field holds focus, move focus to an element of your own first. A list opened after Foundry 14 moves the window is placed and heard in the window that then holds the trigger, its focus and measures included, as Overlays states. Its trigger, row, tile and type figures, its colours beyond what this section states, the default glyph, the list’s placement, width and height, which glyphs a query matches and their order, and its essence-icon-picker-* and data-popover-* hooks are private. disabled and bounds are not published at version 1, and triggerClass, triggerStyle, onTriggerContextMenu and onTriggerKeydown never are, so each is refused, as is a class.
A worked picker follows: a reagent’s icon on a panel inside a Fabricate window, for example in an extension target.
// After `load(['IconPicker'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the picker describes none: draw your own control there.
if (fabUi?.describe?.('IconPicker')?.overlays !== true) return;
let icon = reagent.icon;
const props = () => ({
value: icon,
// Fabricate adds the caption it draws, so the trigger is named "Reagent icon, Flask".
ariaLabel: game.i18n.localize('ACME.ReagentIcon'),
listLabel: game.i18n.localize('ACME.ReagentIcons'),
searchLabel: game.i18n.localize('ACME.SearchReagentIcons'),
searchPlaceholder: game.i18n.localize('ACME.SearchIcons'),
noMatchesText: game.i18n.localize('ACME.NoReagentIconMatches'),
onChange: async (next) => {
icon = next;
picker.update(props()); // Before any `await`, so the trigger shows the new glyph at once.
await reagent.update({ icon });
},
});
// Omit `overlayHost` to draw the list in the Fabricate window around `target`.
const picker = fabUi.mount('IconPicker', { target, props: props() });
// `picker.destroy()` when the panel goes away, moving focus first if the picker holds it.
ActionMenu
ActionMenu draws Fabricate’s overflow menu (<Menu> in the design-system library): an icon-only trigger button showing Fabricate’s overflow glyph, which opens a menu of commands, in an overlay, each of which onSelect reports as it is chosen. The trigger is the only focusable element inside target, so to return focus to the ActionMenu, focus its trigger, target.querySelector('button'). items is required and is an array of the menu’s commands, in order, each { id, label, icon, disabled, danger }, of which id and label are required. id is a string unique within items, which onSelect reports. label is the item’s final display text and its accessible name, and it names the command, not the record, because the trigger identifies the record. A label too long for the menu is cut with an ellipsis, and its whole text stays its name. icon is a Font Awesome class string drawn before the label and hidden from assistive technology, and an item without one keeps the glyph’s column empty. disabled: true draws the item dimmed as a natively disabled button, which the arrow keys skip and a press does not choose. danger: true draws the item in the danger family’s text ink, which clears 4.5:1 on the menu’s ground and on a hovered or focused item in every palette. In foundry-native that ink is the window’s ordinary text ink, so let the item’s label, not its colour, state what it does, and give a danger item an icon. Fabricate drops an item’s data and never writes it, and any other member is private. With items empty, or every item disabled, a press opens a menu with no item to choose, focus rests on the menu itself, and Escape, Tab or a press outside it closes it; with no command to offer, leave the menu unmounted. ariaLabel is required and is final display text naming the trigger and the menu, as “Reagent actions for Flask”, and it is also the trigger’s tooltip, shown as the IconButton section states. Never pass a name of white space alone, which leaves the trigger and the menu with no name. align is 'end' or 'start' and defaults to 'end', and any other value is private. With 'end' the menu lines up with the trigger’s end edge, for a trigger at a row’s end, and with 'start' with its start edge, for one at a list’s start; either way it is kept inside its host’s left and right edges where the host is wide enough to hold it. onSelect is a required callback, called with one argument, the chosen item’s id, each time the user chooses an enabled item by pointer, Enter or Space. It is not called by mount, update, opening or closing the menu, the arrow keys, Escape, Tab, a press outside the menu, or the repeats of an Enter held on the trigger. A menu marks no item selected or current, and each choice of an enabled item calls it, the item chosen last time included. Fabricate calls onSelect only with the id of an item the menu draws when it is chosen. Run a command only for an id you match by name, with no closing else, so no item, the last one included, runs a command meant for another id.
- A press on the trigger, by pointer, Enter or Space, opens the menu and moves focus to its first enabled item, outside
target. After a pointer press, the focus Fabricate moves into the menu shows the mark it shows after a key: the item takes its raised fill and a 1px accent ring drawn inside its edge, and a menu with no item to choose takes the window’s accent ring, 2px wide and 2px clear of it. - ArrowDown on the trigger does the same, and ArrowUp opens the menu onto its last enabled item.
- An Enter held on the trigger opens the menu once, and an Enter held on an item chooses it once; the repeats of either choose and open nothing, and a fresh Enter on an item chooses it.
- A second press on the trigger closes the menu without choosing and moves no focus, so focus goes where the pointer press puts it, which in Chromium, Foundry’s desktop client, is the trigger.
- In the menu, ArrowDown and ArrowUp move focus to the next and the previous enabled item, wrapping at either end, and Home and End move it to the first and the last.
- A choice calls
onSelect, closes the menu, and then returns focus to the trigger, so focus thatonSelectmoves before it returns goes back to the trigger; to move focus in response, move it from a later task, as from asetTimeout. - Escape in the menu closes it without choosing and returns focus to the trigger before the key reaches Foundry, so Foundry’s dismiss keybinding closes no window; whether an open ApplicationV1
Dialog, which listens for Escape itself, also closes is private. - Tab and Shift+Tab in the menu close it without choosing and return focus to the trigger, departing from the APG menu button pattern, in which Tab closes the menu and moves on, as Tab in an
IconPicker’s query field does; the published behaviour is kept so your Tab handling does not change. - A press on a disabled item or between the items chooses nothing and leaves the menu open, and the arrow keys still move among the enabled items.
- A press outside the menu closes it without choosing, and focus goes where the press puts it: to the element you pressed when it, or an element around it, takes focus, and otherwise to the page. With focus on the page, the next Escape reaches Foundry, which asks every open window to close.
- The trigger announces the menu with
aria-haspopup="menu"and its open state witharia-expanded, and the menu is arole="menu"ofrole="menuitem"items named byariaLabel, with no selection state. - The trigger stops the propagation of ArrowDown and ArrowUp and of its own
click, so your listener abovetargethears none of them, and every other key on the trigger bubbles as it does from any button. The open menu stops everyclickinside it, so your listener on theoverlayHostor above it hears none, and every key pressed in the menu, Escape included, may reach that listener.
The menu is the component’s overlay, so describe('ActionMenu').overlays is true, and it is drawn in the host Overlays picks when it opens. Pass an overlayHost inside the same Fabricate window, or none, because the menu’s items, their focus mark and the theme are drawn as this section states only under a .fabricate ancestor; in your own window or dialog pass none, and the menu opens on the standalone layer. The menu opens below the trigger, or above it where the host has room above and none below, and its placement inside the host is otherwise private. ActionMenu takes no rest props, so a data-* prop is refused with "<key>" is not a prop of ActionMenu. Its trigger, items and marks come from Fabricate’s module sheet, rooted at .fabricate-action-menu and .fabricate-action-menu-panel, and it is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, its open menu on the standalone layer there. The trigger’s keyboard ring is the window’s accent ring, 2px wide and 2px clear of the trigger, and an item under keyboard focus takes a raised fill and a 1px accent ring drawn inside its edge. With no item to choose, the menu itself takes the window’s accent ring, 2px wide and 2px clear of its edge. The trigger’s ring clears 3:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, so mount the menu on one of those grounds and leave room for the ring inside any edge of your own that clips. The item’s ring clears 3:1 against its raised fill over the menu’s ground, and against that ground, in every palette. An update keeps the trigger, so focus stays on it, and an update while the menu is open redraws its items in place, focus staying on the item that holds it while that item is still drawn and enabled; destroy removes the trigger and closes the menu, so where the trigger or an item holds focus, move focus to an element of your own first. A menu opened after Foundry 14 moves the window is placed and heard in the window that then holds the trigger, its focus and arrow keys included, as Overlays states. Its glyph, its trigger, menu, item and type figures, its colours beyond what this section states, the menu’s placement and width, an item’s tone, and its manager-action-menu-* classes and data-action-menu-* hooks are private. disabled, heading, panelLabel, triggerIcon, triggerTitle and open are not published at version 1, and triggerClass, menuClass, triggerProps and trigger never are, so each is refused, as is a class.
A worked menu follows: a reagent row’s commands on a panel inside a Fabricate window, for example in an extension target.
// After `load(['ActionMenu'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the menu describes none: draw your own control there.
if (fabUi?.describe?.('ActionMenu')?.overlays !== true) return;
const menu = fabUi.mount('ActionMenu', {
target,
props: {
items: [
{ id: 'duplicate', label: game.i18n.localize('ACME.Duplicate'), icon: 'fas fa-copy' },
{ id: 'delete', label: game.i18n.localize('ACME.Delete'), icon: 'fas fa-trash', danger: true },
],
// The trigger names the record; each item names only its command.
ariaLabel: game.i18n.format('ACME.ReagentActions', { name: reagent.name }),
onSelect: (id) => {
// Each command by its own id, and no closing `else`; each from a later task, so the focus
// Fabricate returns to the trigger does not overwrite focus the command moves.
if (id === 'duplicate') setTimeout(() => duplicateReagent(reagent), 0);
else if (id === 'delete') setTimeout(() => confirmDeleteReagent(reagent), 0);
},
},
});
// `menu.destroy()` when the panel goes away, moving focus first if the menu holds it.
Modal
Modal draws Fabricate’s dialog (<Modal> in the design-system library): a panel drawn over the window, in an overlay, with a header band holding your title, an optional subtitle and a close control, then your body and footer in their content slots. It is for one step the user finishes or dismisses before going on. It draws nothing focusable inside target, so return focus to an element of your own, the control that opened the dialog, unless trapFocus returns it, as the lines below state. open is true to draw the dialog and false or absent to draw none, and you open and close it only through update. While it is closed, target is empty under a Fabricate root and holds only the empty standalone style root elsewhere, and while it is open, target holds one empty element of Fabricate’s, inside that root where it is written, which is private. An update replaces every prop, so pass the dialog’s other props with open on each one, title, closeLabel and onClose among them. An update that closes the dialog detaches the slot elements with their contents intact, and one that opens it attaches the same elements again, so the content-slot rules on detaching apply on every close and open, and your components, effects and listeners in them keep running. A component with an overlay that you mount in a slot closes its open panel when such an update detaches the slot, as Overlays states, so when you open the dialog again its trigger has aria-expanded "false". title is required and is final display text, drawn as the dialog’s level-3 heading, and it is the dialog’s accessible name. subtitle is optional final display text drawn under the title in a quieter, smaller ink than the title, and it is neither part of the name nor announced as the dialog’s description. closeLabel is required and names the close control, as “Close”, and it is also that control’s tooltip, shown as the IconButton section states. Never pass a name of white space alone, which leaves its element with no name. icon is optional Font Awesome classes for a glyph drawn in the header band before the title, hidden from assistive technology and inked in the accent; absent, or '', no glyph is drawn. It names nothing, so title stays the dialog’s accessible name, and a class absent from the running Foundry’s Font Awesome build draws an empty box. size is 'sm', 'md' or 'lg' and defaults to 'md': a dialog 500px, 560px or 620px wide, each clamped to 48px short of the width of the box it is centred in, which is the padding box of the nearest ancestor that makes itself the containing block of fixed content, as contain: layout and a transform do, such as your overlayHost region or a Foundry window scaled with a transform, and otherwise the viewport of the browser window that holds it. A value outside the set, a number included, draws 'md', and the dialog states no inline style for any of them. body is a content slot whose element is a <div>, and the dialog draws its top-level children, as the slot element draws no box, below the header in a padded column it spaces by gap. footer is a content slot whose element is a <div>, and the dialog draws its top-level children in a footer band, spaced by gap and laid out as footerLayout states, of which you make at most one primary. An omitted slot draws no body or no footer band, so a dialog with neither draws its header alone. The dialog’s height is capped, so scroll tall content inside one element of your own in the body, which you give min-height: 0 and overflow: auto, and tabindex="0" when it holds no control, so the keyboard can scroll it. Give your dialog at least one control of your own, so focus has somewhere to go when it opens; a dialog that only informs puts its acknowledging button in the footer. closeOnOutsideClick is true or false and defaults to true. With true, a click of the primary button whose press goes down and comes up outside the dialog and outside every panel that counts as inside it, as the lines below state, calls onClose as its click fires, as does a tap, and so does Escape pressed while focus is outside both. A press with any other button, a press that goes down outside and comes up inside the dialog or such a panel, or the reverse, and a click with no pointer press, as a keyboard activation of a control outside makes, call nothing. In a DialogV2, with true and the opener still holding focus inside it, Escape calls onClose and also reaches the DialogV2’s own Escape listener, so both close; pass closeOnOutsideClick: false, stop Escape in your own listener, or move focus into the dialog first. A press on the control that opened the dialog is an outside press too, and its own click follows onClose, so if your opener opens the dialog on every press, pass false, or ignore a click whose press began while the dialog was open. A panel counts as inside the dialog from when it opens until it closes, wherever it is drawn, when a control inside the dialog opened it or a panel that counts as inside it did, as the panel of a component with an overlay that you mount in a slot: a Select’s list, an IconPicker’s list and query field and an ActionMenu’s menu. A press in such a panel does not call onClose, and the panel takes it as its own section states, so a click on an option chooses it as it does outside a dialog. Escape pressed while focus is in such a panel is left to that panel: the dialog neither calls onClose nor stops it, and the panel closes and returns focus to its trigger in the dialog, so Foundry’s dismiss keybinding closes no window; whether an open ApplicationV1 Dialog, which listens for Escape itself, also closes is private. A Modal you mount in a slot counts as inside the dialog too, so a press or an Escape in its dialog, or a press on its scrim, calls only that dialog’s onClose, and a panel opened from inside that Modal counts as inside both, so a press there calls neither and an Escape there closes the panel alone. An overlayHost you pass inside the slot draws your panel inside the dialog, which clips what overflows it. With false, neither a press nor an Escape outside the dialog calls onClose. onClose is a required callback, called with no argument, when the user asks to close the dialog: a press on the close control by pointer, Enter or Space, Escape in the dialog, and, as closeOnOutsideClick states, a click or an Escape outside it. An Escape held down calls it again on each repeat. It is not called by mount, update, destroy or a press inside the dialog. Fabricate does not close the dialog itself: it stays open until your update closes it or you call destroy, so to keep it open, as before a step that would lose work, do nothing; only while target is disconnected is the dialog not drawn, as Overlays states. If you close the dialog while focus is on it or inside it, or in the panel of a component with an overlay that you mount in a slot, first move focus to an element of your own, as the opener, because removing the focused control, or detaching a slot that holds the panel’s trigger, leaves focus on the page; with trapFocus, Fabricate returns it a frame later, as the lines below state.
Without trapFocus:
- Fabricate moves no focus: when the dialog opens, focus stays where it was, so move it into your own content from a later task, as from a
setTimeout, once the dialog is drawn. - Tab moves focus as the browser does from any element but the dialog itself, so it can leave the dialog, except that Tab in the query field of an
IconPickeryou mount in a slot moves on from that picker’s trigger, as its section states, and that an open ApplicationV1Dialogin the main window takes a Tab pressed anywhere outside thatDialog, in this dialog too, and moves focus to its own button. - Unless
scrimis'dim', nothing covers the window behind the dialog, which still takes pointer and keyboard input; with'dim'the scrim takes the pointer presses over it, asscrimstates, and the keyboard still reaches that window. - The dialog is a
role="dialog"named bytitleand is not announced as modal, with a scrim or without one, because Tab can move focus out of it and the window behind it still takes keyboard input; move focus into the dialog when it opens and back to its opener when it closes. - An Enter held on the control that opened the dialog presses whatever then holds focus on each repeat, so move focus into the dialog onto an element that does not act on Enter, or ignore a
keydownwhoserepeatistrue. - A pointer press on the dialog’s surface, outside every control, moves focus to the dialog itself, which holds Foundry’s keybindings off and draws no focus ring, so Escape then calls
onCloseas Escape in the dialog does, and Tab or Shift+Tab then moves focus to its first or its last control, unless an open ApplicationV1Dialogtakes the Tab, as above.
trapFocus is true or false and defaults to false; Fabricate does not coerce it to a boolean, so only true and false are in the contract: the string 'false' traps focus. With true, as the dialog is drawn Fabricate moves focus into it, onto the control initialFocus names or else its first control, the close control, and the dialog carries aria-modal="true", so it is announced as modal. Tab from its last control moves focus to its first, Shift+Tab from its first to its last, and a Tab with focus on the page, as after the focused control was removed, moves focus into it. Every key but Escape pressed in the dialog bubbles to its host and the host’s ancestors and stops at the document, so no bubble-phase window listener hears it, Foundry’s keybindings among them. Unless scrim is 'dim', nothing covers the window behind the dialog, which still takes a pointer press, so a press there can move focus out of the dialog; with 'dim', a press over the box the scrim covers lands on the scrim and focus stays in the dialog. A frame after an update closes the dialog, or destroy removes it, Fabricate returns focus to the element that held it as the dialog opened, if focus is then on the page and that element is still connected, enabled and not the page; otherwise focus stays where it is, so a trapped dialog you open in that frame keeps the focus it took. An Enter held on the control that opened the dialog presses the control focus entered on with each repeat, the close control included, so name a control that does not act on Enter with initialFocus, or ignore a keydown whose repeat is true. Pass trapFocus in the update that opens the dialog and keep it until the one that closes it; what changing it while the dialog is open does is private. initialFocus is optional text that names where focus enters with trapFocus: the first control in the dialog, in document order, that carries a data-initial-focus attribute equal to the text or sits inside an element that does, so mark an element of your own in a slot, as a search field or the target of a published component you mount there. The text is compared as it is and never read as a selector, so where no control matches, or the value is no string, focus enters on the first control, and without trapFocus it moves nothing. Fabricate does not ask whether a control is drawn, so mark a control that is drawn: a hidden one takes no focus, which stays where it was. It is read as the dialog opens, so an update that changes it takes effect the next time the dialog opens. footerLayout is 'end' or 'equal' and defaults to 'end': 'end' draws the footer’s top-level children in a row aligned to the end of the band, and 'equal' gives each of them one equal share of the band’s width, in the order you append them. A child takes its share as a box, so a Button you mount in an element of your own there fills it only with fullWidth. What the footer draws for a value outside the set is private; today that is 'end'. scrim is 'none' or 'dim' and defaults to 'none': 'none' draws no layer behind the dialog, and 'dim' draws a scrim, a translucent layer in the palette’s own dark overlay colour, under the dialog and over the window behind it. A value other than 'dim', as 'dim ', 'DIM', true or 1, draws none, because Fabricate compares the value as it is and coerces none. The scrim is drawn in the dialog’s host just before the dialog and at its z-index, so it covers the box the dialog is centred in, as the lines on its host below state, and it stacks where the dialog does: the dialog and everything in it are drawn above it and keep their own colours, and a Foundry window stacked above the window that holds it is not dimmed. It is drawn in the frame the dialog is drawn in, with no fade, so reduced motion changes nothing, and under forced colours Chromium draws it in the system’s background colour at the same opacity, with the dialog’s 1px edge in the system’s text colour above it. Over the four page grounds of every palette it never lowers the contrast of the dialog’s 1px edge with the window behind and raises it to 3:1 in none, the edge measuring 1.66:1 to 2.51:1, so the dialog’s own controls, not its boundary, carry its identification, and the dim sets the dialog apart by fading the window’s content. It carries aria-hidden="true" and no role, so Chromium leaves it out of the accessibility tree, and it takes no focus and is never a Tab stop, but it covers no keyboard path: without trapFocus, Tab moves focus onto the dimmed controls behind the scrim, whose focus ring the scrim fades under 1.7:1, as Fabricate’s accent ring measures 1.35:1 to 1.69:1 against the dimmed page grounds of every palette, and the dialog is not announced as modal, so pass trapFocus true whenever you pass 'dim'. It takes every pointer press over the box it covers, so none reaches the window behind there, and a press on it keeps focus where it is. It is outside the dialog, so with closeOnOutsideClick true a primary-button click that goes down and comes up on it calls onClose as its click fires, and with false calls nothing. A press with another button, a drag from the scrim into the dialog and a drag from the dialog onto the scrim call nothing. The press’s mouseup and click land on the scrim, so where onClose closes the dialog nothing behind the scrim hears either. A wheel or a touch drag over the scrim does not scroll what is under it. For a dim of another colour or strength, over another box, or with a blur, pass 'none' and draw your own layer, as the lines on its host below state. Each of trapFocus, initialFocus, footerLayout, icon, size and scrim was added at version 1, so a Fabricate that predates it refuses it with "<key>" is not a prop of Modal; read describe('Modal').props before you pass one.
In every mode:
- Escape pressed while focus is in the dialog calls
onClose, prevents its default and stops at the dialog, so a field you draw in a slot does not clear on it, Foundry’s dismiss keybinding closes no window and an open ApplicationV1Dialogdoes not close. - Escape pressed on an element inside the dialog whose
aria-expandedis"true"when the key goes down, or inside one, is left to that element: the dialog neither callsonClosenor stops it, so your own expanded control stops the Escape it handles, or the key reaches Foundry’s dismiss keybinding wherever the element then focused does not take keyboard input. - An element of yours in a slot that stops Escape itself keeps the dialog from calling
onClose, and so does a published component mounted there that stops Escape, as aSelect’s or anIconPicker’s trigger does, so Escape on such a trigger whose list is closed calls noonCloseand the dialog stays open. Fabricate’s own dialogs differ: there the dialog hears an Escape on a closedSelectorIconPickertrigger before the trigger does, and closes. - Escape reaches your own
keydownlisteners inside the dialog’s slots before it stops. - Escape with focus on the page, or on an element that Foundry does not treat as taking keyboard input and that is outside both the dialog and every panel that counts as inside it, reaches Foundry’s dismiss keybinding, which, unless it first cancels a canvas drag or closes Foundry’s main menu, a context menu or a tour, asks every open window to close, and when none closes releases the controlled objects or opens the main menu; with
closeOnOutsideClicktrueit also callsonClose. - Escape on the close control leaves the tooltip it shows under keyboard focus open until focus leaves the control or the dialog closes.
- Every other key and every press inside the dialog bubbles to its host and the host’s ancestors, never through the
Modal’s owntarget, and withtrapFocusa key stops at the document.
The dialog is the component’s overlay, so describe('Modal').overlays is true, and it is drawn in the host Overlays picks when it opens. Pass an overlayHost inside the same Fabricate window, or none, because the close control, its ring and the theme are drawn as this section states only under a .fabricate ancestor, and in no <form>, <label>, <a> or <button> and under no element that carries data-action, because a press or a key in the dialog bubbles to the host’s ancestors and a text field or an untyped button you draw in a slot would act on them; in your own window or dialog pass none, and the dialog opens on the standalone layer. The dialog is centred in the nearest element above it that makes itself the containing block of fixed content, as contain: layout and a transform do and a Foundry window or its content can, and clipped where that element clips its overflow; otherwise it is centred in the viewport of the browser window that holds its host, so it may extend past the Fabricate window’s edges. It sits above the host’s other content that sets no higher z-index, and under any Foundry window stacked above the window that holds it; in the standalone layer it sits above every Foundry window. An overlayHost that is a region of your own, such as a pane inside your window, draws the dialog inside that region, centred in it where the region makes itself the containing block of fixed content, as contain: layout and a transform each do, and centred in the browser window’s viewport, outside the region, where it does not, as a region that is only position: relative or only container-type: inline-size does not. Either also makes the region the stacking context and the containing block for its own fixed and absolute descendants. In a region that is the containing block, the dialog’s width is capped 48px short of the region’s padding box, so it stays inside the region with a 24px margin on each side of that box, and its close control stays inside the region. A region wider than the browser window draws the dialog at the region’s width, past the window’s edge, and a region 48px wide or narrower draws it with no content width. With scrim 'none', Fabricate draws no scrim: no layer covers the region behind the dialog, which keeps taking pointer input, and if you dim your region, draw a layer of your own in it, which the dialog is drawn over where that layer sets a z-index below 100. With 'dim', the scrim covers the box the dialog is centred in: the region alone where the region makes itself the containing block of fixed content, so pass such a region to dim your own pane and nothing else, and the viewport where neither the region nor an element above it does, over a layer of yours whose z-index is below 100 either way. Pass a region that does not itself scroll, such as the root that holds your scroller; in a region that scrolls, the scrim and the dialog scroll with its content. The way to dim your own window is that contained host, a non-scrolling root of yours such as your studio’s root that makes itself the containing block of fixed content, with trapFocus true; dimming the viewport, with no such region, is the fallback. The dialog’s width is capped by the width of the box it is centred in, which is the region’s where the region is its containing block and the browser window’s otherwise. Its height is capped by the browser window’s height, never by the region’s, so a region shorter than the dialog clips it only where the region is its containing block and clips overflow. Its height and placement are otherwise private. Modal takes no rest props, so a data-* prop is refused with "<key>" is not a prop of Modal. Its close control and its ring, and the theme its inks resolve from, come from Fabricate’s module sheet, and its frame, header band and close control are drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, its dialog on the standalone layer there. A target in its body or footer slot sits inside the dialog on that layer, so a component you mount there is under a Fabricate root and is drawn with no standalone style root of its own. The close control’s keyboard ring is the window’s accent ring, 2px wide and 2px clear of the control, and it clears 3:1 against the header band in every palette. The title and the subtitle clear 4.5:1 against the header band in every palette, and the close glyph clears 3:1 against it in every palette. An update while the dialog is open redraws its header in place and keeps its slot elements, so focus stays on a control you drew there; destroy removes the dialog, so where the dialog or a control in it holds focus, move focus to an element of your own first. A dialog opened after Foundry 14 moves the window is placed and heard in the window that then holds target, as Overlays states. A dialog left open across a move hears no outside press or outside Escape in the new window and still hears those of the window it left; in the new window it judges an expanded control from its attribute as it then stands, not as the key went down. Its frame, band, type and spacing figures, its colours beyond what this section states, its width, height and placement, the element it keeps in target, and its manager-modal-* classes and data-manager-modal* hooks are private. onSubmit and width are not published at version 1, and dialogProps and initialFocusSelector never are, so each is refused, as is a class. A <form> Fabricate drew around both slots would make an untyped button you draw in one submit it, so for a form-style dialog wrap your fields in a <form> of your own in the body slot, handle its submit, and submit it from a footer Button’s onclick with requestSubmit().
A worked dialog follows: renaming a reagent from a button of yours on a panel inside a Fabricate window, for example in an extension target.
// After `load(['Modal'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the dialog describes none: draw your own dialog there.
if (fabUi?.describe?.('Modal')?.overlays !== true) return;
// `opener` is a button of yours in the same Fabricate window, outside `target`.
let isOpen = false;
let openAtPress = false;
const props = () => ({
open: isOpen,
title: game.i18n.localize('ACME.RenameReagent'),
closeLabel: game.i18n.localize('ACME.Close'),
body: true,
footer: true,
onClose: () => close(),
});
const dialog = fabUi.mount('Modal', { target, props: props() });
const field = document.createElement('input');
field.type = 'text';
field.value = reagent.name;
field.setAttribute('aria-label', game.i18n.localize('ACME.ReagentName'));
dialog.slot('body').append(field);
const save = document.createElement('button');
save.type = 'button';
save.textContent = game.i18n.localize('ACME.Save');
dialog.slot('footer').append(save);
function show() {
isOpen = true;
dialog.update(props());
// From a later task, once the dialog is drawn, onto the field, which does not act on Enter.
setTimeout(() => field.focus(), 0);
}
function close() {
// Before the update removes the focused control, so focus is not left on the page.
opener.focus();
isOpen = false;
dialog.update(props());
}
// A press on the opener while the dialog is open closes it as its `click` fires, before your own
// `click` listener runs, which must not open it again.
opener.addEventListener('pointerdown', () => {
openAtPress = isOpen;
});
opener.addEventListener('keydown', () => {
openAtPress = false;
});
opener.addEventListener('click', () => {
const pressedOpen = openAtPress;
openAtPress = false;
if (!pressedOpen && !isOpen) show();
});
// An Enter held onto Save presses it once, not on each repeat; it matters only if you focus Save.
save.addEventListener('keydown', (event) => {
if (event.key === 'Enter' && event.repeat) event.preventDefault();
});
save.addEventListener('click', async () => {
close();
await reagent.update({ name: field.value });
});
// `dialog.destroy()` when the panel goes away, moving focus to the opener first if the dialog holds it.
ListRow
ListRow draws the design system’s list row (<ListRow> in the library): a mark, a name, an optional detail and an optional quantity on one bordered row, which with onOpen is one whole-row button. Without onOpen it draws nothing focusable; with it, the button is the only focusable element Fabricate draws inside target, so to return focus to the row, focus target.querySelector('button'), which a control you draw in trailing follows in document order. name is required and is final display text, drawn as the row’s name with its whole text as the name’s native title, and with onOpen it opens the button’s accessible name. detail is optional final display text drawn after the name, and '' or absence draws none. quantity is a number or a string drawn at the row’s end in tabular figures, 0 included, and null or absence draws none. With onOpen the button’s accessible name is its text in the order it is drawn: leading, the name, badges, meta, the detail, then the quantity; meta is also the button’s description, so it is read twice. art is an image path drawn as the row’s mark, with no alternative text, and '' or absence draws icon instead. icon is a Font Awesome class string drawn as the mark where there is no art and hidden from assistive technology, and it defaults to 'fas fa-box'. tint is one of Avatar’s tint keys, and it recolours the glyph alone, as Medallion’s does. tone is 'neutral', 'positive', 'danger' or 'accent' and defaults to 'neutral': 'positive' draws the row on the success fill and edge, 'danger' on the danger ones and 'accent' on the accent ones, and any other value draws as 'neutral' and is never refused. It adds no text or glyph, so state what the tone means in the row’s text as well, as a state word in detail or a published Chip in badges. Each tinted fill is translucent and replaces the row’s own, and on it the name, and the row’s ink that the detail and the quantity take, clear 4.5:1 over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette; a muted name on it falls short of 4.5:1 on --fab-bg-2 in some palette. A published Chip with no emphasis in badges reads its label over its own fill over the row’s: on each tinted row the default chip, with no tone, and the positive, warning, info and accent chips clear 4.5:1 over those four grounds in every palette, and so does danger but for a 'positive' row on --fab-bg-2, while the neutral chip falls short on every tinted row. So draw a state word as one of the chips that clear, or as detail. A published Button with the accent role in an 'accent' row’s trailing clears 4.5:1 for its label, at rest and hovered, and 3:1 for its edge over those grounds in every palette. selected: true draws the selected face over an 'accent' row, as over a 'positive' one: the active wash replaces the accent wash and the edge stays the accent row’s own, so a selected accent row and an unselected one look alike. So say in the row’s text which row is selected, as the face is not announced without onOpen. With onOpen the pointer over an 'accent' row replaces the accent wash with the hovered fill, --fab-surface-raised. Under forced colours Chromium draws each tinted fill in the system’s Canvas at the fill’s own alpha and the edge in CanvasText, so the tone is not seen there and the row’s text carries it. A Fabricate that predates 'accent' draws it as 'neutral' and refuses nothing, which describe('ListRow') cannot show. muted is true or false and defaults to false, and true dashes the row’s edge and draws the name in the muted ink. markSize is 22, 26, 28, 30, 34 or 38 and defaults to 22: it is the mark’s edge in CSS pixels, a rung of Medallion’s art ladder drawn at that rung’s corner, and it sizes nothing while leading is drawn. While busy replaces leading, it sizes the spinner. Any other value, a numeric string included, draws 22, and Fabricate warns in the console. density is 'dense' or 'default' and defaults to 'dense': 'default' draws the roomier row of Fabricate’s own browse lists, at a 12px by 16px inset with a 12px gap and an 11px corner, and any other value draws as 'dense'. layout is 'row' or 'card' and defaults to 'row': 'card' draws the row as a card, its mark above its name and the rest in one column across target’s width, at a 12px inset on the card ground with an 11px corner, and any other value draws as 'row'. truncateName is true or false and defaults to false: true holds the name and the detail each on one line that ends in an ellipsis where its text overflows, the whole text staying in the DOM and in a native title, and false wraps them. With badges, a truncated name keeps at least six characters’ width, and narrower than that the badges wrap beneath it. detailAlign is 'start' or 'end' and defaults to 'start', and it is read only with truncateName: 'end' holds the detail at the row’s trailing edge, at most 40% of the row’s width, and 'start' lets it take up to half the row after the name; any other value draws as 'start'. selected is true or false, or absent or null: true draws the selected face, an accent edge and the active fill, and with onOpen writes aria-pressed="true" on the button, false writes aria-pressed="false" there, and absence or null writes no aria-pressed, so the button is a plain button. Any other value but null is read as false, and a selected danger row keeps its danger fill and takes a 1px accent edge inside its border. Without onOpen the face is drawn on the row’s own box and inset, so a selected row stands the height of its neighbours, and nothing is written for it, so the face is seen and not announced: say what it means in the row’s text as well, in detail or badges. The face’s name and its ink, which the detail and the quantity take, clear 4.5:1 on its translucent fill over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette; a muted name over it clears 4.5:1 only on --fab-bg-0, and its accent edge falls short of 3:1 against each of those grounds in some palette, so the text carries the meaning. Do not pass muted beside selected: true on a ground other than --fab-bg-0. disabled is true or false, defaults to false, and is read only with onOpen: true disables the button natively, so a press calls nothing and the button leaves the tab order, and dims the row. current is true or 'step', or absent: true marks the row as the current item of its list and 'step' as the current step of a sequence, by writing aria-current="true" or aria-current="step" on the button with onOpen and on the row’s root without it, and false or any other value writes none. It draws nothing, so pass selected: true beside it to draw the current row’s face. With onOpen, selected also writes aria-pressed, so pass it beside current only where the press toggles that selection; a pressable current row that toggles nothing takes current alone, and its text says it is current. Mount a sequence’s rows into li targets of an ol, so “current step” is read with the list’s position. A screen reader that reports aria-current reads a read-only current row in reading order with its text and the state current, or current step; the row takes no focus, so Tab passes it. busy is true or false and defaults to false: true marks the row’s work in flight, drawing a spinning glyph, hidden from assistive technology, in place of the mark or of leading, and writing aria-busy="true" on the button with onOpen and on the row’s root without it. With onOpen the busy button also takes aria-disabled="true", never disabled, so it keeps its focus and its place in the tab order, shows the progress cursor, and a press calls no onOpen; beside disabled it stays natively disabled and takes no aria-disabled. The row draws no busy text, so say what is in flight in detail where the wait is perceptible, and pass busy: false when the work ends. While busy the row detaches the slot element of leading, and attaches the same one again, with its content intact, when busy ends. Fabricate coerces none of muted, truncateName, disabled and busy to a boolean, so only true and false are in the contract: the string 'false' dashes the row, truncates its name, disables its button and marks it busy. onOpen is an optional callback, called with no argument, on each press of the button by pointer, Enter or Space while it is not disabled; passing it draws the whole row as one button, and omitting it draws the read-only row. It is not called by mount, update or destroy. The row draws no state of its own: a press shows a new selected only when your update passes it. aside is a content slot whose element is a <div>, drawn on a line of its own beneath the row’s mark, name, detail and quantity, across the row’s inner width; requesting it draws the row at the inset Fabricate gives a row with an aside. The row draws the content slot’s children in normal flow, with no gap of its own, so fill it with one element of your own that lays out its content; text there takes the row’s ink and type, as the detail does. With onOpen the aside sits beneath the layer the button draws over the row, so a pointer press anywhere on it presses the button, and the button’s aria-describedby names the element holding the slot, so the aside’s text is read as the button’s description. So draw text and marks there, as a published FillBar or Chip, and nothing focusable or pressable, without onOpen too, because an update that passes onOpen covers it. For the same reason a native title you put on your content there never shows while the row has onOpen, because the pointer rests on the button’s layer, not on that content. The row never moves aside while it is requested: an update that adds or drops onOpen, or changes any other prop, keeps the slot element in place. leading is a content slot whose element is a <span>, drawn first in the row’s content in place of the mark, so art, icon and tint are ignored while it is requested. You draw a glyph or image of your own there, marked aria-hidden="true" where it adds nothing to the button’s name. badges is a content slot whose element is a <span>, drawn after the name on the name’s line, and wrapping beneath a name that fills the line. meta is a content slot whose element is a <span>, drawn beneath the name and its badges, and with onOpen the button’s aria-describedby names it too. trailing is a content slot whose element is a <span>, drawn after the row’s content at the row’s end, beside the button and above the layer the button draws over the row. It is the one slot that may hold controls: draw one or more compact controls there, each a <button type="button" data-keyboard-focus="true"> that acts on the row’s item, as an edit button, a published Button or IconButton among them, and a press on one does not call onOpen. Append each control, or a plain <span> mount target for each, as a child of the slot element: each child is a flex item spaced by the row’s gap, 8px on a dense row and a card and 12px at the 'default' density, all on one line that never wraps, and no control shrinks. The name gives up its width first, wrapping onto more lines, down to no width at all, where it is drawn a letter to a line. Where the controls are wider than the row’s inner width, a row with onOpen moves them to a line of their own beneath the name, where they still run past the row’s edge, and a row with no form keeps them beside a name of no width and runs them past its edge; in a card they always take a line of their own beneath the content. So measure your controls together with their gaps, and draw no more than leave the name a readable width at the narrowest width you mount the row at. Each control is its own stop in the tab order: Tab reaches the row’s button, then each control in the order you appended them, and none of them joins the button’s accessible name. Give each control an accessible name of its own that names the row’s item, as Remove Ember salt, because an icon-only control beside its neighbours has no text of its own, and chips go in badges. disabled dims the whole row and disables no control in trailing, so set each control’s own disabled. The dimmed row also dims an enabled control in trailing, a press between two controls opens nothing, and one on the row’s inset beyond the last control presses the row’s button. Give each control a target of at least 24 by 24 CSS pixels. Requesting leading, badges or meta draws the row at the inset Fabricate gives a row with an aside, and trailing alone does not. Draw text and marks in leading, badges and meta, as a published Chip, and nothing focusable or pressable: with onOpen they lie inside the button, so a press on them presses it and calls onOpen, and an update that passes onOpen covers them without it. Draw only phrasing content there (text, span, an i or img that is aria-hidden or has an alt), because with onOpen the hosts sit inside a native button, which forbids blocks, lists and headings, and an alt, aria-label or title on that content joins the button’s accessible name. The module sheet lifts them above the layer the button draws over the row, so a native title you put on your content there shows, unlike in aside. An update that adds or drops onOpen moves leading, badges and meta, and one that requests the first of onOpen, leading, badges, meta, aside, a density of 'default' and a layout of 'card', or drops the last, moves trailing; only aside never moves. Fabricate detaches the slot element and attaches the same one in its new place, with its content intact, and the browser resets what it resets on those, as Mounting, updating and destroying states, which for a control in trailing includes focus. So change none of those props while focus is inside trailing, and move focus to an element of your own first where you must. A Fabricate that predates aside, leading, badges, meta, trailing, markSize, density, layout, truncateName, detailAlign, current or busy refuses each with "<key>" is not a data attribute, and describe('ListRow').props shows whether the running one publishes it; adding one is additive, and the entry stays at version 1. One that predates current and busy draws no face for a selected without onOpen, and refuses nothing for it. No other published prop draws a control inside the row: leading, badges and meta lie inside the button and aside beneath its layer, so draw a control that acts on the row’s item in trailing, or beside the row, outside target, after the row in focus order.
ListRow takes rest props, data-* attributes that land on the row’s root, not on the button, so no rest name is reserved; Fabricate writes its own data-list-row there after them, so a prop of that name is not written. ListRow needs a Fabricate window ancestor, because its row, button and marks come from Fabricate’s module sheet, rooted at .fabricate-list-row. Your own window or dialog carries no Fabricate root, so the row is refused there with ListRow needs a Fabricate window ancestor. The button’s keyboard ring is the window’s accent ring, 2px wide and drawn 2px inside the row’s edge on a layer that covers the row, in place of the ring the module draws around a button. The row paints its own opaque fill, --fab-bg-1, or --fab-bg-2 as a card, and the ring clears 3:1 against it in every palette; the selected, hovered, success, danger and accent fills are translucent and replace it, so they sit over the ground beneath the row, and the ring clears 3:1 against each over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, so mount the row on one of those grounds. An update that keeps onOpen keeps the button, so focus stays on it; one that passes or omits onOpen where the last did not draws or removes the button in the same row, so where the button holds focus, move focus to an element of your own first. destroy removes the row. Its figures and its colours beyond what this section states, its fabricate-list-row-* classes beyond its root, its data-list-row hook, and how Fabricate draws a row in its own lists and headings are private. inset and bodyBasis, and the children snippet, are not published at version 1, and openProps, nameClass and class never are, so each is refused.
A worked list follows: one selectable row per reagent, in a panel inside a Fabricate window, for example in an extension target.
// After `load(['ListRow'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the row describes none: draw your own row there.
if (fabUi?.describe?.('ListRow')?.props.onOpen?.kind !== 'callback') return;
const props = (reagent) => ({
name: reagent.name,
detail: reagent.kind,
quantity: reagent.quantity,
art: reagent.img,
selected: reagent.id === selectedId,
onOpen: () => select(reagent.id),
'data-acme-reagent': reagent.id,
});
const rows = reagents.map((reagent) => {
const target = document.createElement('li');
list.append(target);
return fabUi.mount('ListRow', { target, props: props(reagent) });
});
function select(id) {
selectedId = id;
// Every prop again on each update; the pressed row keeps its button and its focus.
for (const [index, row] of rows.entries()) row.update(props(reagents[index]));
}
// `row.destroy()` for each row when the panel goes away, moving focus first if a row holds it.
ToggleCard
ToggleCard draws the design system’s toggle card: a bordered card holding a glyph, a title with a second line under it, and a switch, for one setting that is on or off. The switch is the one StatusToggle draws, so its keyboard, focus, forced-colours and ring rules are that section’s. The card is not itself a control: a press on the title or the second line does nothing, and the switch is the only focusable element Fabricate draws in target. title is required final display text, the setting’s name, drawn as the card’s title and used as the switch’s accessible name, the same in both states. A name of white space alone leaves the switch with no name, so never pass one. The name never states a position, so no “on”, “off”, “show” or “hide” at its start or end, as StatusToggle states. sub is optional final display text drawn under the title in a quieter ink; absent, the second line is empty. It is not part of the switch’s name: while it is a non-blank string it is the switch’s description, which Fabricate ties to it through aria-describedby, so a screen reader reads it after the name when the switch takes focus; absent, blank or not a string, the switch carries no aria-describedby. A Fabricate that predates this draws the second line and describes nothing by it, refuses nothing, and describe cannot show it, so put a sentence that must be heard there in title. icon is optional Font Awesome classes for the glyph drawn before the title, hidden from assistive technology; absent, a circle glyph is drawn, and '' draws no glyph and gives the copy the glyph’s width. on is true or false, and is required: true draws the switch on, false off, and the card’s own edge and fill follow on only through tone. Fabricate coerces nothing, so only true and false are in the contract. The card changes nothing itself: a press reports through onToggle, and the switch shows the new state when your update passes it, which may be after the press returns. To refuse the change, pass on unchanged and say why in text of your own, so the card never shows a state you do not hold. semantics is pressed or switch, and defaults to pressed: pressed exposes the state with aria-pressed and states no role, and switch states role="switch" and exposes it with aria-checked; a value outside the set draws pressed. Pass pressed or switch as StatusToggle states. tone is neutral, enabled, locked or info, and defaults to neutral. It tints the card while on is true: enabled in the success family, locked in the accent family and info in the info family, each an edge on a soft fill with the second line in the secondary ink so it still reads on the tint. neutral, a card whose on is false and a value outside the set draw the resting face, and nothing is thrown. Choose it by what the setting means to your user, enabled for a preference that is switched on, locked for one that is enforced and info for an informational policy. The tint only decorates: the switch’s aria-pressed or aria-checked and its track say whether the card is on, and a tone’s edge falls short of 3:1 against the ground in some palettes, so never rely on the colour to say it. Under forced colours the system draws the card’s edge in its text colour and the switch’s track is still filled when on and hollow when off, and the tint declares no transition of its own. A Fabricate that predates tone refuses it with "tone" is not a prop of ToggleCard, and describe('ToggleCard').props shows whether the running one publishes it; adding it is additive, and the entry stays at version 1. onToggle is a required callback, called with no argument each time the switch is pressed, each repeat of a held Enter key included. Work out the new state from the on you last passed. It is not called by mount, update or destroy. The switch has no unavailable state at version 1, as StatusToggle states, and the card takes no disabled. A card is drawn the same in the Manager, the player window and, under the standalone style root, a companion’s own window or dialog, and it grows to the width of target. It takes no rest props, so a data-* attribute is refused with "<key>" is not a prop of ToggleCard. Its padding, gap, corner, border and fill figures, its type figures, its colours beyond what this section and StatusToggle state, and the hooks and classes Fabricate’s own callers use are private.
A worked card follows: a setting of your own, named by the title the card draws.
// After `load(['ToggleCard'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the card describes none: draw your own control there.
if (!fabUi?.describe?.('ToggleCard')) return;
let spend = acmeSettings.spendOnStart;
const props = () => ({
title: 'Spend when this stage begins',
sub: 'The ingredient is used up as the stage starts.',
icon: 'fa-solid fa-hammer',
on: spend,
semantics: 'switch', // The press writes the setting at once.
onToggle: () => {
spend = !spend;
acmeSettings.spendOnStart = spend; // Your own state first.
card.update(props()); // Every prop again, with the new `on`.
},
});
const card = fabUi.mount('ToggleCard', { target, props: props() });
SelectionCheckbox
SelectionCheckbox draws the design system’s checkbox: a native <input type="checkbox">, visually hidden, inside a <label> that draws a square box beside your label, for one choice that is ticked or not. A pointer press anywhere on the box or the label presses the input, and in the labelled form the input is the only focusable element Fabricate draws in target, inside the standalone style root in a target with no Fabricate root, so target.querySelector('input') reaches it; the decorative form draws no focusable element. An update keeps the same input, so focus stays on it while its state changes; destroy removes it, so where it holds focus, move focus first. The input is named by label, the text its wrapping <label> draws, or, where you pass it, by ariaLabel, which must then hold that text. label is required final display text, drawn after the box and wrapping beside it, the box on its first line; it may be absent or '' beside a non-blank ariaLabel, which waives it, and white space alone beside a non-blank ariaLabel draws as absent. It may also be absent or '' beside decorative: true, which draws no label. Without either, mount refuses with SelectionCheckbox requires a non-empty "label". A label of white space alone beside no non-blank ariaLabel is refused as an empty one, with SelectionCheckbox requires a non-empty "label". ariaLabel is optional final display text naming the input in place of label; beside a non-blank label it must contain the label’s words as one run of whole words, or mount and update throw "ariaLabel" must contain the text of "label" ("<label>" is not in "<name>"), and beside no label it is the box’s only name and the box draws alone. Pass it where the visible label is too short to say what ticking does, as “Ember salt spent when this stage begins” beside the label “Spent”; “Spend Ember salt when this stage begins” beside “Spent” is refused, because “Spent” is not among its words. An ariaLabel that is blank or not a string is dropped and names nothing, so the name is the label’s. checked is true or false, and is required: true draws the box filled in the accent with a tick and states the input checked, and false draws it empty. Fabricate coerces nothing, so only true and false are in the contract: another truthy value, the string 'false' among them, draws the box ticked, 0 and null draw it empty, and an absent or '' checked is refused with SelectionCheckbox requires a non-empty "checked". indeterminate is true or false, and false when absent: true draws the box edged in the accent on its soft fill with a dash in place of the tick, whatever checked is, and states the input mixed. Any value but true, the string 'true' among them, draws the box by checked alone. A mixed box is passed as checked: false with indeterminate: true: mixed means some of the things the box stands for are ticked, so a press asks for true. disabled is true or false, and false when absent: true disables the input, draws the box at half opacity and the label in the muted ink, and the box keeps its tick, dash or empty face, so the state stays readable. A disabled input takes no focus, is left out of the tab order and reports nothing, so say why in text beside it; another truthy value disables it too, as only true and false are in the contract. A disabled box is drawn at half opacity, its edge, fill and glyph together, beside the not-allowed cursor, so it reads as unavailable while its face stays legible; WCAG 2.2 §1.4.11 asks no contrast of an inactive control, and the figures below are the enabled box’s. density is compact, default or comfortable, and default when absent: a 16, 20 or 22px box beside a label set on 16px lines, 18px beside the 22px box, its first line centred on the box; a value outside the set draws default. The compact box draws no fill, so its edge and empty face sit on the ground beneath it; the default and comfortable boxes fill --fab-bg-0. tone is default or success, and default when absent: success draws a ticked box that is not mixed filled with --fab-success inside a --fab-success-strong edge, its tick in --fab-on-success, at every density and on the labelled and the decorative box alike, for a row that is done; a value outside the set draws default, the accent. A success box that is empty or mixed draws as a default one, so a mixed box keeps its accent dash, and the tick, not the colour, says the box is ticked; under forced colours a ticked success box fills with Highlight as a default one does. Over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in all seven palettes the success edge clears 3:1, 3.94:1 at the least, and its tick clears 3:1 on its fill, 4.79:1 at the least. onChange is a required callback, called with one argument, true or false, the state a press asks for: the opposite of the checked last passed, so a press on a mixed box whose checked is false asks for true. It may be absent beside decorative: true, which never calls it. It is called once for each press, by pointer on the box or the label or by Space on the focused input, and not by mount, update or destroy. The box changes nothing itself: the input and the box keep the checked and indeterminate you last passed until your update passes new ones, which may be after the press returns, so to refuse the change pass them unchanged and say why in text of your own. Until your update lands, assistive technology hears the old state, so update inside onChange, optimistically, and roll the update back if your own write fails. aria-describedby is an aria key: Fabricate writes it on the input. Pass the id of one element of yours, or several ids separated by spaces, holding visible text beside the box that says more than its name, such as what ticking it does. Each id exists in the tree that holds target while the box is shown, and the element it names, which may be beside target and need not be inside it, is not hidden; an id that does not exist is skipped and the others are still read. Rest data-* attributes land on the input itself, so data-keyboard-focus, data-action, data-cursor, every data-tooltip name, and the two names Fabricate’s own stylesheet reads off its own buttons, data-validation-focused and data-essence-sort-direction, are refused with "<key>" is reserved on SelectionCheckbox. The box therefore opens no tooltip, so put what ticking it does in text beside it, tied to it with aria-describedby. decorative is true or false, and false when absent: true draws the box alone, aria-hidden="true", with no <label>, no input and nothing focusable, for a row of yours that is itself the control, as a <button type="button" aria-pressed> whose own text names it and whose aria-pressed states what the box shows. Only true draws it: any other value, the string 'true' and 1 among them, draws the labelled box and needs its name and onChange. Beside decorative: true, checked, indeterminate, density and tone draw the box as they draw the labelled one, and checked is still required; label, ariaLabel, disabled, onChange, aria-describedby and the rest data-* attributes are checked as on the labelled box, then drawn nowhere, and onChange is never called. The box is not a pointer target and reports no press, so the press, the focus, the name, the state, the disabled state and its dimming are your row’s, and you keep the box’s checked equal to the state your row states. The box draws no hover or press feedback of its own, so your row draws it. Strike through your row’s text, not the row: text-decoration on the row reaches the box’s tick, and the line crosses it. Chromium’s tree shows your row’s button with its name and pressed state and no node of the box, inside a <button aria-pressed> row. The seam draws the box under the standalone style root, a <div> drawn as display: contents, in a target with no Fabricate root, so a <span> target inside your <button> holds that <div>, which the HTML content model does not allow there though the browser draws it; mount where a Fabricate root is above target to avoid it. An update may move a box between the decorative and the labelled form; the labelled form’s input is then a new element, so move focus first where it matters. The <label> is the pointer target, at least 24px tall around the box and as wide as the box and its label; around the 16 and 20px boxes it reaches 4px and 2px past the box above and below, and on every side of a box drawn with no label, and it is drawn above in-flow neighbours, so keep 4px clear of any other control around a compact box and 2px around a default one, horizontally as well as vertically, or the target takes the pointer where it overlaps them. The target lies over the label text, so a drag across the label selects none of it. The keyboard ring is the accent, 2px wide and 2px clear of the box, drawn on the box around its visually hidden input whether or not a Fabricate root is above target, so it reaches 4px beyond the box on every side; leave that much inside any edge of yours that clips. A focused ticked box shows its accent fill, a gap of the ground and the ring, so the ring stays apart from the box’s edge. The state is not carried by colour alone: a ticked box draws a tick, a mixed one a dash, and an empty one neither, and the input states it to assistive technology as checked, mixed or not. Under forced colours the box draws in the reader’s system colours: an empty box keeps its edge and draws no tick, a ticked or mixed one fills with Highlight and draws its glyph in HighlightText, a disabled box draws its edge in GrayText, and fills with it when ticked or mixed, undimmed, and the ring takes the reader’s text colour. Over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in all seven palettes an empty box’s edge clears 3:1, 3.34:1 at the least, against the ground a compact box draws on and against the fill the larger boxes enclose. A ticked or mixed box’s accent edge clears 3:1, 5.19:1 at the least. The tick clears 3:1 on the accent fill, 5.90:1 at the least, and the dash on the soft fill, 3.94:1 at the least. The label clears 4.5:1, 6.91:1 at the least, and the disabled label still clears it, 4.99:1 at the least. Under the pointer an enabled empty box raises its edge to --fab-text-muted, 4.99:1 at the least, and never below its resting edge. --fab-bg-3 is not a supported ground for the box or its label: there the empty edge falls short of 3:1 in three palettes, 2.14:1 at the least, the label falls short of 4.5:1 in two, 3.51:1 at the least, and the ring falls short in two. The contrast figures are read from the palettes and the layout is measured in Chromium; the role and name are read from Chromium’s own accessibility tree, the checked, mixed and disabled states are the native input’s own mapping, and no screen reader was run. A press through the seam is measured in happy-dom and by one View Lab step, not by another real-browser test. A box is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, and it is no wider than target. Its label and empty edge are inks of the dark scheme the standalone style root states, so on Foundry’s light theme paint --fab-bg-1 on target; that shortfall is inferred from those inks, not measured. A Fabricate that predates it does not list SelectionCheckbox in components, describe answers null for it, and mount refuses it with "SelectionCheckbox" is not published, so draw your own control there. A Fabricate that predates decorative and tone refuses them with "decorative" is not a data attribute and "tone" is not a data attribute, and its describe lists neither, so read describe('SelectionCheckbox').props.decorative first and draw your own box where it is absent. Its gap, corner and type figures, its colours beyond what this section states, its wrapper and input props, and the hooks Fabricate’s own callers use are private.
A worked box follows: a flag of your own, named by the label it draws.
// After `load(['SelectionCheckbox'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the box describes none: draw your own control there.
if (!fabUi?.describe?.('SelectionCheckbox')) return;
let grant = acmeSettings.grantIngredients;
const props = () => ({
checked: grant,
label: 'Award the recipe’s ingredients first',
density: 'compact',
'aria-describedby': 'acme-grant-hint', // Your own visible hint beside the box.
onChange: (next) => {
grant = next;
acmeSettings.grantIngredients = grant; // Your own state first.
box.update(props()); // Every prop again, with the new `checked`.
},
});
const box = fabUi.mount('SelectionCheckbox', { target, props: props() });
A decorative box follows, in an objective row of your own that is its own pressable button.
// A Fabricate that predates `decorative` describes no decorative form: draw your own box there.
if (!fabUi?.describe?.('SelectionCheckbox')?.props.decorative) return;
const row = document.createElement('button');
row.type = 'button';
const slot = document.createElement('span'); // The box's target.
const text = document.createElement('span');
text.textContent = 'Gather three iron ore'; // Your row's name; strike it through yourself when done.
row.append(slot, text);
const boxProps = (done) => ({ checked: done, decorative: true, tone: 'success' });
const mark = fabUi.mount('SelectionCheckbox', { target: slot, props: boxProps(objective.done) });
row.setAttribute('aria-pressed', String(objective.done));
row.addEventListener('click', () => {
objective.done = !objective.done; // Your own state first.
row.setAttribute('aria-pressed', String(objective.done));
mark.update(boxProps(objective.done));
});
Disclosure
Disclosure draws the design system’s disclosure card (<Disclosure> in the library): a bordered card whose head is one button, inside a heading, that shows and hides the card’s body. The button carries aria-expanded and aria-controls, which names the body, and it is the only focusable element Fabricate draws in target, so target.querySelector('button') reaches it. The card paints its own --fab-bg-2 fill inside a 1px --fab-border edge with an 11px corner, and it grows to the width of target. open is read for truthiness and defaults to false: a truthy value shows the body and writes aria-expanded="true" on the button, and any other writes aria-expanded="false" and hides the body; Fabricate coerces nothing, so the string 'false' opens the card. The card draws no state of its own: a press reports through onToggle, and the card opens or closes when your update passes the new open, which may be after the press returns. A closed body stays in the page under the hidden attribute and is never removed, so what it holds keeps its state, a typed value among it, and it leaves the tab order and the accessibility tree while hidden. An update that closes the body while focus is inside it drops focus to the document body, as hiding any focused element does, so move focus to the button first. onToggle is a required callback, called with one argument, the state asked for, true from a closed card and false from an open one, on each press of the button by pointer, Enter or Space while it is not disabled, each repeat of a held Enter key included. It is not called by mount, update or destroy; to refuse the change, pass open unchanged. level is 2, 3, 4, 5 or 6 and defaults to 3: the button sits inside a heading of that level, an h2 to an h6, and any other value, 1, a numeric string such as '4' or a non-integer among them, draws an h3. Pass the level that follows the heading above your cards, so a screen reader’s heading list reaches each card at its place in the page. disabled is read for truthiness and defaults to false: a truthy value writes aria-disabled="true" on the button and draws the head at 62% opacity with its chevron still pointing its way; the string 'false' disables it too, because Fabricate coerces nothing. The head keeps its Tab stop and its focus, so an update that disables the focused head leaves focus on it, and a press, Enter or Space there asks for nothing. The body keeps its state and stays shown or hidden as open says, and a control you draw in an open body stays enabled, so set that control’s own. head is a content slot whose element is a <span>, drawn inside the button before the chevron, its children laid out in a wrapping row 8px apart. The button’s accessible name is the text you draw in head, in the order it is drawn, and Fabricate adds none. Draw the card’s name as text in head. The name is read in drawn order, so anything drawn before the card’s name, such as a tier chip, is read first; keep it to a word or two. Draw each figure in one span, because the head’s items are read with a space between them, so a figure split across elements is read in pieces. aria-expanded supplies open or closed, and a head with no text leaves the button unnamed. A glyph there is an i that is aria-hidden, or an img with an alt (empty when decorative). An icon-only head MUST carry its name as an img with a non-empty alt or an element with role="img" and an aria-label that matches what it shows. Put no aria-label on any other element there. Every word in the head joins the button’s name and the heading’s entry in a screen reader’s heading list, and version 1 has no description channel and no form without a heading, so keep a run of holdings short and put the detail in body. Foundry’s core sheet makes a button’s children pointer-transparent, so a press anywhere on the head presses the button, and a native title on your content there never shows. Draw only phrasing content there, text, a span or a published Chip or FillBar, and nothing focusable or pressable, because the slot sits inside a native button; a list there is read as part of the name, not as a list, so draw it as a run of spans. Fabricate watches the slot, and when an element in it can take focus the mount faults: your onFault is told with a TypeError naming the element’s tag, and target is left empty, as Mounting, updating and destroying states. The elements it refuses are a link or an image map area with an href, a button, an input that is not hidden, a select, a textarea, a label, a details or summary, an iframe, embed or object, an audio or video with controls, an img with a usemap, and any element with a tabindex or that is contenteditable; it reads the slot’s light DOM alone, so it does not see into a shadow root there. body is a content slot whose element is a <div>, drawn in the body element the button’s aria-controls names, at a 12px inset under a 1px --fab-border rule. It may hold anything, controls included, which follow the button in focus order while the body is shown. The body is no region landmark and is not named by the button, so a page of many cards adds no landmark for each. The module sheet draws the chevron as two edges of a turned square in --fab-text-muted, pointing down while the card is closed and up while it is open, and turns it at once, so the card draws no motion under either prefers-reduced-motion setting; the head draws its hover fill and ring in the frame they begin, not over the half second Foundry’s core sheet tweens every button by. Under the pointer a head that is not disabled takes the --fab-surface-raised fill, and under keyboard focus it shows the window’s 2px accent ring drawn 2px inside the card’s edge. The head is at least 38px tall across the card’s inner width, so its target is 24px and more. Over the seven palettes the chevron reads 4.99:1 to 8.38:1 on the card’s fill and 4.33:1 to 7.11:1 on the hover fill, the ring 5.19:1 to 9.35:1 and 4.18:1 to 7.89:1, and --fab-text 8.14:1 or more on either. The edge reads 1.26:1 to 1.53:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2, so the head’s text and chevron, not the edge, mark the card out. Under forced colours the chevron is drawn in ButtonText, and in GrayText at full opacity while disabled, and the ring in Highlight, so open and closed differ by the chevron’s shape, never by colour alone. A card is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog. Disclosure takes rest props, data-* attributes that land on the card’s root, not on the button, so no rest name is reserved. The root wraps the head and the body, so a rest data-action fires for a press anywhere inside the card, the body’s controls included, and a rest data-tooltip shows over the whole card; pass neither. A Fabricate that predates it refuses mount('Disclosure', …) with "Disclosure" is not published, and describe('Disclosure') returns null, so draw your own card there; adding it is additive, at version 1. An update keeps the button, its heading and the body element, so focus stays on the button, except one that changes level, which draws the heading and the button again around the same head slot element, so where the button holds focus, move focus first. destroy removes the card. Its padding, gap and type figures beyond what this section states, its fabricate-disclosure-* classes beyond its root, its is-open class, how the chevron is drawn, and its body element’s id, which is unique to each mount, are private.
A worked card follows: one faction of your own, whose head holds a published Chip, the faction’s name and standing, and a published FillBar.
// After `load(['Disclosure', 'Chip'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the card describes none: draw your own there.
if (!fabUi?.describe?.('Disclosure')) return;
let open = false;
const props = () => ({
open,
level: 3, // The faction list sits under a level-2 heading of yours.
head: true,
body: true,
onToggle: (next) => {
open = next; // Your own state first.
card.update(props()); // Every prop again, with the new `open`.
},
'data-acme-faction': faction.id,
});
const card = fabUi.mount('Disclosure', { target, props: props() });
// The head is phrasing content: spans and published leaves, nothing focusable.
const head = card.slot('head');
const tier = document.createElement('span');
const name = document.createElement('span');
name.textContent = `${faction.name} ${faction.standing > 0 ? '+' : ''}${faction.standing}`;
const bar = document.createElement('span');
bar.style.cssText = 'display: block; flex: 0 0 72px';
head.append(tier, name, bar);
const chip = fabUi.mount('Chip', { target: tier, props: { tone: 'positive', children: faction.tier } });
const standing = fabUi.mount('FillBar', {
target: bar,
props: { value: faction.standing, origin: 'center' },
});
// The body may hold anything, and keeps it while closed.
card.slot('body').append(renderFactionDetails(faction));
// `chip.destroy()`, `standing.destroy()` and `card.destroy()` when the panel goes away.
Typeahead
Typeahead draws the design system’s typeahead: a search field whose list of suggestions the query drives, for one choice from a set too long to step through, which commits as it is made, and optionally for text of your own when nothing matches. It is an editable combobox: the input holds focus throughout and names the active row, and the list is an overlay. An empty query lists nothing here unless you pass openOnEmpty, which shows a short set whole before any typing; the field never shows the current value’s label, so draw your current value beside it. The input is the only focusable element Fabricate draws in target, so to return focus to the typeahead, focus target.querySelector('input'). options is required and lists the rows the current query yields, in drawn order, each { value, label, icon?, detail? }: value is a string or a number, label is required final display text, icon is optional Font Awesome classes for a glyph drawn before the label and hidden from assistive technology, and detail is optional final display text drawn as a second line under the label; a row’s accessible name is its label followed by its detail. Fabricate filters nothing: you hand the list the rows your own search yields for the query you hold, in your own order and number, so cap a long result yourself; Fabricate draws every row it is given inside the list’s scroll. An item whose value is not a string or a number, or whose label is not a non-blank string, is not drawn; an icon or a detail that is not a non-blank string draws nothing. Two items that share a value are both drawn, both carry the current tick, and each reports that value, so keep values unique. An options that is not an array is a contained fault reported under Typeahead, which empties target and reports to onFault; an empty array lists no row. A member other than value, label, icon and detail is private. query is the text in the field, a string, and is '' when absent. A query that is not a string is outside the contract, and what is drawn for it is private. It is a value prop: the field changes it itself as the user types, and an update that omits it keeps the current query, so you need not pass the query back on every update. onQueryChange is called with two strings, (next, previous), each time an edit of the user’s changes the query: a keystroke, a paste or a cut, a clear the browser makes from the field’s cancel button, and Escape while nothing is shown, which reports ''. It is not called by mount, update, a choice or Enter. Answer it with an update that passes the options the new query yields, in the same handler and before any await, so the list never shows rows for an older query. value is your current value, optional: the row whose value is value, matched by ===, carries a tick at its end and aria-checked="true". While value is a string or a number every other row carries aria-checked="false", and while it is absent or null no row carries aria-checked and none is ticked. The current row also takes Select’s chosen fill beside its tick. Some screen readers say “not checked” on every other row while value is set; how a screen reader reads aria-checked on an option is its own. A value that is neither a string, a number nor null is outside the contract, and what is drawn for it is private. onChange is a required callback, called with one argument, the chosen row’s value exactly as options passed it, so a number stays a number, each time the user chooses a row by pointer or by Enter on the active row, the current row included. It is not called by mount, update, typing, opening or closing the list, Escape, Tab, a press outside the list or Enter with no row active. The typeahead changes nothing itself on a choice: the query and value stay as they were, and you pass what you keep through update, as query: '' to empty the field after a choice. A choice closes the list until the query is edited again, and Enter at that query then commits nothing more; under openOnEmpty it stays closed until the user edits the query, focus comes back to the input or ArrowDown on a blank query opens it, so a query you pass through update after the choice, as query: '', synchronously or later, does not reopen it. ariaLabel is required and names the input and its list, final display text naming what is searched, as “Find a reward”. The typeahead draws no caption, so draw the same words as visible text beside it, and never pass a name of white space alone, which leaves the field with no name. placeholder is optional final display text shown while the field is empty, and is not the field’s name. emptyLabel is optional final display text, as “Nothing matches.”, that the list shows as one quiet line in place of rows while the input holds focus on a non-blank query and options draws no row; absent or '', the list closes instead. Fabricate always draws a hidden polite status region, an element with role="status", beside the field inside target, empty while the line is not shown, and writes the line into it when the line is shown and empties it when a row is listed again, so a screen reader is expected to announce the line once; the list’s own line is not a second region. That region is the second element with role="status" in target; the first is the field’s own count region, which countLabel writes. How a screen reader treats a live region is the screen reader’s, and Fabricate announces no count of rows of its own, so put any count in countLabel. countLabel is optional final display text drawn after the input inside the field, as “4 more, keep typing”, in the field’s own polite status region, as SearchField’s countLabel draws it; '' or absence draws none. Use it to say how many rows a capped result leaves out, and keep it short, because past half the field it is cut. allowFree is true or false, and defaults to false: while it is truthy, Enter pressed outside an IME composition with no row active reports the query through onFreeText, unless the query is blank, and takes the key whatever the query; Enter on an active row still chooses the row. Fabricate coerces nothing, so the string 'false' turns it on, and only true and false are in the contract. onFreeText is a callback, required while allowFree is truthy, called with one argument, the query with its leading and trailing white space removed, as your user’s own text when no row is wanted. It is not called by a press, by Enter on an active row, by Enter on a blank query or inside a composition, or while allowFree is falsy. It changes nothing itself either: empty the field with query: '' in an update when you take the text, as the worked example does. openOnEmpty is true or false, and defaults to false: while it is true, focus on a blank query, or ArrowDown there after Escape, a choice or a press outside closed the list, opens the list with every row options passes, so pass the whole set for ''; Fabricate still filters nothing, and the rows follow your options as the query changes. Only the literal true turns it on: Fabricate coerces nothing, so the string 'false', the string 'true' and 1 leave it off, and only true and false are in the contract. Opening leaves no row active, so the first ArrowDown of an open list reaches the first row; the list opens on focus whether the press, Tab or a script moved focus there, and a press on an input that already holds focus does not reopen a list Escape or a choice closed, which ArrowDown or an edit does. While it is true and options draws no row for a blank query, emptyLabel shows there as it does for a query that matches nothing, and is said into the status region. Use it for a short set the user should see whole, as a picker among a handful of scopes; a set too long to read at a glance stays a typed search, and a set the user never searches is a Select. A Fabricate that predates openOnEmpty refuses it with "openOnEmpty" is not a prop of Typeahead, and its describe('Typeahead') omits it, so pass it only where describe('Typeahead').props.openOnEmpty is present. density is 'default', 'toolbar' or 'inline' and defaults to 'default': the field’s shell at the heights SearchField’s density draws, 38px at radius 9, 34px at radius 9 and 30px at radius 7; any other value, 'compact' included, draws 'default'. error is optional final display text: while it is a non-blank string the field takes the error face, Select’s danger edge on the --fab-danger-soft fill, its input states aria-invalid="true", and the text is drawn beneath the field in the --fab-danger-text ink and is the input’s description through aria-describedby; absent, '', white space alone or not a string, none of them is drawn. While the input holds focus, the field’s lit border is drawn in place of the danger edge, and the fill and the message stay. The danger edge falls short of 3:1 against the grounds below, and forced colours remove the fill, so the message carries the error, and say what to do in it. While an error shows, the list opens below the message, so it never covers it. The message makes the field taller, so draw a field that can show an error at the 'default' density, in a place that need not stay one height. A Fabricate that predates Typeahead does not list it in components, describe('Typeahead') answers null, and mount refuses it with "Typeahead" is not published, so draw your own field there.
- The list is open only while the input holds focus, the query is not blank or
openOnEmptyistrue, andoptionsdraws a row oremptyLabelshows; a press outside the field and the list, or a choice, closes it until the query is edited, and focus coming back to the input after a press outside opens it again. - ArrowDown and ArrowUp move the active row and wrap at each end, ArrowDown from no active row to the first and ArrowUp to the last; each edit of the query leaves no row active, so a query typed again never brings a row back.
- While nothing is shown, ArrowDown on a blank query opens the list with no row active and takes the key only while
openOnEmptyistrue; otherwise it passes to the page. - The input names the active row with
aria-activedescendant, the row statesaria-selected="true"and draws a 2px accent ring inside its edge, and the list scrolls it into view; focus stays in the input throughout. - Home and End move the caret in the field, and move the active row to the first or the last row only when the caret already stands at that end of the text; PageUp and PageDown leave the list alone.
- Enter chooses the active row, leaves no row active and closes the list until the query is edited; with none active it chooses nothing, and while rows are listed it takes the key.
- Escape while the list or its empty line is shown closes it and keeps the text. Escape while nothing is shown and the query is not empty empties it, which reports
''throughonQueryChange. Either stops its propagation, so no listener abovetargethears it, a DialogV2’s own included. Escape on an empty query passes untouched, so a DialogV2 that listens for it closes. UnderopenOnEmptythe list stays closed at the query Escape emptied, so the sequence on a typed query is close, empty, then pass on, and an edit, focus coming back to the input or ArrowDown opens it again. - Tab and Shift+Tab move focus as the browser does and close the list without a choice, and your listener above
targethears the Tab. - No key is acted on inside an IME composition, and a key Safari reports with
keyCode229 counts as one, so Enter that ends a composition chooses nothing. - A press on a row chooses it and closes the list, and the input keeps focus, because a press inside the list does not take it; the pointer over a row fills it and moves no active row.
- Enter in the input, outside IME composition, cancels the implicit submission of the
<form>the input is in, asSearchFielddoes.
The input is a role="combobox" with aria-autocomplete="list", aria-expanded and, while rows are listed, aria-controls; the list is a listbox named by ariaLabel, and each row an option. The line emptyLabel draws is shown in the overlay with no listbox. The list is the component’s overlay, so describe('Typeahead').overlays is true, and it is drawn in the host Overlays picks when it opens. Pass an overlayHost inside the same Fabricate window, or none, so the list takes that window’s palette; in your own window or dialog pass none, and the list opens on the standalone layer. The list opens beneath the field, and above it where its host has no room beneath; its placement, width and height inside the host are private. Its width has a 220px floor, so beside a field narrower than that in a narrow window it can overhang the window’s edge. The list also closes, and its panel is removed, when target leaves its document while the mount is live, as when an update of a Modal whose content slot holds the mount closes the dialog, as Overlays states. A row is at least 28px tall, so each is a 24px target. Typeahead takes no rest props, so a data-* prop is refused with "<key>" is not a prop of Typeahead. Its field is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog; it fills the width of target, so give target display: flex. The keyboard mark is SearchField’s: while the input holds focus the shell’s 1px border takes the accent and the input draws no ring of its own. A row’s label and detail and the empty line clear 4.5:1 on the list, on a row under the pointer and on the current row’s fill in every palette, and the active row’s ring and the tick clear 3:1 there; the list paints its own opaque ground, so what it opens over changes none of those. On the error fill, the query and the placeholder clear 4.5:1, and the lit border 3:1, over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in every palette, and the message’s ink clears 4.5:1 on those grounds; none of them is stated over --fab-bg-3. Under forced colours the active row’s ring is drawn in the system highlight colour and the current row keeps its tick in the text colour, so the two stay apart by shape, and the current row’s fill, which forced colours remove, is never the only carrier; colour is never the only carrier of either. An update keeps the input, so focus and the caret stay where they are unless the query is replaced, and an update while the list is open redraws it in place; destroy removes the input and closes the list, so where the input holds focus, move focus first, as Ownership and theme states. Its sizes beyond the field’s height and corner, its glyph, tick and colours beyond what this section states, and what it draws for a member or value outside its contract are private. source, itemLabel, itemIcon, onChoose, label, ariaLabelledBy, icon, inputProps, listClass, listProps, listMaxHeight, optionClass, optionHeight and optionDataAttr are not published at version 1, so a class or any of those is refused with "<key>" is not a prop of Typeahead.
A worked typeahead follows: a reward picked from your own catalogue, or named in free text, which your own row then shows.
// After `load(['Typeahead'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the typeahead describes none: draw your own field there.
if (!fabUi?.describe?.('Typeahead')) return;
// Your text above `target`, in the same Fabricate window: <span>Find a reward</span>.
target.style.display = 'flex';
let query = '';
const props = () => ({
ariaLabel: 'Find a reward', // The words your text draws.
placeholder: 'Search the catalogue',
options: acmeCatalogue.search(query, 8).map((item) => ({
value: item.id,
label: item.name,
icon: 'fa-solid fa-gem',
detail: item.category,
})),
value: acmeReward.id ?? null,
emptyLabel: 'Nothing in the catalogue matches. Press Enter to use what you typed.',
allowFree: true,
onQueryChange: (next) => {
query = next;
typeahead.update(props()); // The rows for the new query, before any `await`.
},
onChange: (id) => {
acmeReward.choose(id); // Your own state first.
query = '';
typeahead.update({ ...props(), query }); // Empties the field without `onQueryChange`.
},
onFreeText: (text) => {
acmeReward.name(text);
query = '';
typeahead.update({ ...props(), query });
},
});
const typeahead = fabUi.mount('Typeahead', { target, props: props() });
Popover
Popover draws the design system’s anchored popover (<Popover> in the design-system library): a small non-modal dialog drawn in an overlay beside an anchor element you own, holding your own controls in its content slot, as a value field, delta buttons and a reason field under a grid cell. It is for an edit the user makes and leaves with Escape or an outside press; for a step the user finishes or dismisses before going on, mount a Modal. It draws nothing focusable inside target, which holds one hidden element of Fabricate’s, inside the standalone style root where one is written, which is private. Mount one Popover per anchor. open is true to draw the panel; absence, false and any other value, 'true' and 1 included, draw none, and you open and close it only through update. An update replaces every prop, so pass the popover’s other props with open on each one, anchorId and onClose among them. An update that closes it detaches the body slot element with its contents intact, and one that opens it attaches the same element again, so the content-slot rules on detaching apply on every close and open. anchorId is required: the id of your anchor element, as the grid cell the popover belongs to, looked up in the document that holds the popover’s target, never in Fabricate’s own document, so in a Foundry 14 detached window it is looked up there. The panel is drawn only while the id names a connected element with a layout box: while it names none, or its element is removed or display: none, the panel is not drawn and no callback is called, and it is drawn again against the element that then carries the id. While target is disconnected, as when an update of another component whose content slot holds it detaches the slot, the panel is not drawn and no callback is called, and it is drawn again once target is attached. A value that is not a string names no anchor, and the first element carrying the id is the anchor, so give it an id unique in its document. Fabricate writes nothing on the anchor: state aria-haspopup="dialog" and aria-expanded there yourself, "false" before the first open, and point its aria-controls at the panel if you wish. The panel’s id is anchorId followed by -popover and its heading’s is anchorId followed by -popover-title, so give no other element either id. placement is 'bottom-start', 'bottom-end', 'top-start' or 'top-end' and defaults to 'bottom-start': the side the panel is tried on first, under or over the anchor and 6px from it, and the anchor edge its own lines up with, the start edge being the left; a value outside the set draws 'bottom-start'. The panel takes the stated side while its content fits between the anchor and 8px short of its host’s edge, or while that side has the more room, else the other side, so it flips at either edge of its host. Its edges are clamped 8px inside its host, its height is capped to the room on the side it takes, and its body scrolls inside it once the cap is reached; where neither side has 48px, it keeps its own height, up to its host’s less 16px, and overlaps the anchor. It is as wide as its content, at most 360px and at most its host’s width less 16px. It is placed again when its document scrolls, when its window resizes, when an update changes placement, when the panel or the anchor changes size, and once per animation frame after its document changes, as when a reflow or a Foundry window’s move shifts the anchor. While the anchor lies wholly outside its window’s viewport or outside an ancestor that clips its overflow, as when its scroller scrolls it away, the panel is hidden, stays open and calls nothing, and it shows again when the anchor returns. title is optional final display text drawn as the panel’s level-3 heading, a level you cannot change, and the dialog’s name where no ariaLabel is passed. One of title and ariaLabel is required: a mount with neither, or with a title of '' and no ariaLabel, is refused with Popover requires a non-empty "title", and a title of white space alone counts as ''. ariaLabel is optional final display text that names the dialog in place of the heading; beside a title it must hold the title’s words, in order and as whole words, or the mount is refused, so the spoken name starts from what is shown. An ariaLabel of white space alone, or that is not a string, is dropped and names nothing; the title names the panel. body is a content slot whose element is a <div>, drawn below the heading in a padded column the panel spaces by gap, which scrolls when the panel’s height is capped. Fill the slot before you open the popover, or in the same task, because focus moves into the panel a microtask after it is drawn. The body takes focus where the slot holds no control, and while it overflows with no control in it, it is also a Tab stop, so the keyboard scrolls it with the arrow keys, Page Up, Page Down, Home and End; it then draws the window’s accent ring 2px wide inside its own edge. The body takes no name of its own: where it takes focus, a reader meets your own content in it. closeOnOutsideClick is true or false and defaults to true; only false turns it off, and any other value, 'false' included, keeps the default. With true, a pointer press anywhere in the document outside the panel calls onClose as its mousedown fires, whichever button it is. A press on the anchor is not an outside press, so your own handler on the anchor decides, as by closing the popover it opened; toggle it on click, never on mousedown or pointerdown. A panel counts as inside the popover from when it opens until it closes, wherever it is drawn, when a control inside the popover opened it, as the list of a Select you mount in the body slot, so a press there calls nothing and the panel takes it as its own section states. With false, no press outside the panel calls onClose, which suits a nudge with a text field a stray press must not discard; the panel then stays drawn above a Foundry window dragged over its anchor, until Escape closes it. onClose is a required callback, called with no argument, when the user asks to close the popover: Escape pressed while focus is in the panel or on the anchor and, as closeOnOutsideClick states, a press outside it. It is not called by mount, update, destroy, a press inside the panel or the anchor going. Fabricate does not close the popover itself: it stays open until your update passes an open other than true or you call destroy.
Focus and keys:
- Focus moves into the panel as it is first drawn in an open, onto its first control, else onto its body, else onto the panel itself, which holds Foundry’s keybindings off and draws no focus ring.
- When the panel is drawn again in the same open, as when its anchor returns, focus moves in only while it is on the page, so a control the user has focused since stays focused.
- Tab on the anchor moves focus into the panel, Tab from its last control moves focus to its first and Shift+Tab from its first to its last, so the keyboard stays in the panel until Escape, which always leaves it, from the panel or the anchor.
- The panel is not announced as modal, and the page behind it still takes pointer input.
- When the panel closes while focus is inside it, Fabricate moves focus to the anchor a frame later, if focus is then on the page and the anchor is connected; a press outside that is not on the anchor or in a panel opened from inside moves focus where the press puts it, so it is left there.
- Escape pressed while focus is in the panel or on the anchor is judged as the key goes down, before any control can stop it: it calls
onClose, prevents its default and stops there, so no listener of yours inside the panel hears it, Foundry’s dismiss keybinding closes no window and aModalthe popover is drawn from stays open. - Escape pressed on an element inside the panel whose
aria-expandedis"true"when the key goes down, or inside one, is left to that element, as an openSelectlist’s is, so the next Escape closes the popover; Escape pressed while focus is elsewhere calls nothing.
The panel is the component’s overlay, so describe('Popover').overlays is true, and it is drawn in the host Overlays picks when it opens, so target’s overflow does not clip it. It is drawn at the popover family’s stacking level, z-index 4000, above a Modal dialog, and a panel a control inside it opens is drawn above it. In a <dialog> opened with showModal() that holds the anchor or target, it is drawn in that dialog, as Overlays states, so it is not inert there. It never animates, with or without a reduced-motion preference, and under forced colours its edge is the system text colour and its shadow is not drawn. Its surface is --fab-bg-0, as the picker panel’s is, with a 1px --fab-border-strong edge and the large shadow, and the title and the body’s inherited ink are --fab-text, which clears 4.5:1 on that surface in every palette; the body’s ring clears 3:1 on it. The edge carries no state and reads between 1.64:1 and 2.21:1 against --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in the seven palettes, so the controls you draw inside carry their own edges. Popover takes no rest props, so a data-* prop is refused with "<key>" is not a prop of Popover. Its panel is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, modal or not, on the standalone layer there. An overlayHost outside every Fabricate window is accepted, and the panel then takes the palette the document’s root names rather than a window’s, and the Fabricate window’s keyboard rings do not reach your controls in its slot. Whether a screen reader announces the panel as a dialog, and by which name, as it takes focus is the reader’s; Fabricate’s suites read Chromium’s accessibility tree only. Its padding, gap, corner and type figures, its colours and placement beyond what this section states, the hidden element it keeps in target, and its fabricate-popover* classes and data-popover-* hooks are private. A Fabricate that predates the popover publishes no Popover: describe('Popover') returns null and mount('Popover', …) is refused with "Popover" is not published.
A worked nudge follows: adjusting a score from its cell in a grid of your own, inside a Fabricate window or your own sheet.
// After `load(['Popover', 'Stepper'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the popover describes none: draw your own there.
if (fabUi?.describe?.('Popover')?.overlays !== true) return;
// `cell` is your button for the score, carrying an id unique in its document.
cell.id = 'acme-score-strength';
cell.setAttribute('aria-haspopup', 'dialog');
cell.setAttribute('aria-expanded', 'false');
let isOpen = false;
const props = () => ({
open: isOpen,
anchorId: cell.id,
title: game.i18n.localize('ACME.Strength'),
body: true,
onClose: () => setOpen(false),
});
const nudge = fabUi.mount('Popover', { target, props: props() });
// The published Stepper inside, a typed field with 24px-or-larger step buttons, appended before
// the popover first opens.
const field = document.createElement('div');
nudge.slot('body').append(field);
let score = 14;
const stepperProps = () => ({
value: score,
min: 1,
max: 20,
ariaLabel: game.i18n.localize('ACME.Strength'),
decrementLabel: game.i18n.localize('ACME.Lower'),
incrementLabel: game.i18n.localize('ACME.Raise'),
onChange: (next) => {
score = next;
stepper.update(stepperProps());
},
});
const stepper = fabUi.mount('Stepper', { target: field, props: stepperProps() });
function setOpen(next) {
isOpen = next;
cell.setAttribute('aria-expanded', String(isOpen));
nudge.update(props());
}
// A press on the cell is not an outside press, so the cell's own click toggles the popover.
cell.addEventListener('click', () => setOpen(!isOpen));
TintSwatches
TintSwatches draws the design system’s swatch strip (<TintSwatches> in the design-system library): a radio group of Fabricate’s tint swatches, for one colour chosen from Fabricate’s tints, as an activity’s or a faction’s colour. It is the strip Fabricate’s own essence editors draw, and Fabricate’s tints are its whole palette: a colour outside them is not offered, because each tint is tuned for every palette and the checked swatch’s ring is measured against those tints alone. The group is one role="radiogroup" element, the only element Fabricate draws directly in target, inside the standalone style root in a target with no Fabricate root, and each swatch in it is a <button type="button" role="radio">, so a swatch never submits a form of yours. The swatches fill the width of target in rows of cells at least 44px wide and 28px tall, 6px apart, wrapping onto a second row where target is narrower than ten cells, so each is a 24px target and more. value is the checked tint’s key, a string matched exactly: 'sage', 'mist', 'lavender', 'rose', 'peach', 'butter', 'aqua', 'mauve', 'verdant' or 'azure'; while it names a swatch that is drawn, that swatch alone states aria-checked="true" and draws the checked ring, and every other states aria-checked="false". Any other value checks no swatch and is not refused: absence, '', null, a capitalised name such as 'Rose' and a token name such as '--fab-tag-rose' among them, because Fabricate coerces nothing. onChange is a required callback, called with one argument, the chosen tint’s key, each time a swatch that is not checked is chosen: by a press, by Space or Enter on the focused swatch, or by an arrow key, Home or End, which move focus onto a swatch and choose it. It is not called by mount, update or destroy, nor by choosing the checked swatch. The strip changes nothing itself: the check stays on the value you last passed until your update passes a new one, which may be after the callback returns, so to refuse the change pass value unchanged and say why in text of your own. Until your update lands, assistive technology hears the old swatch checked, so update inside onChange. ariaLabel is required final display text naming the radio group, as “Activity colour”; a mount without it, or with '', is refused with TintSwatches requires a non-empty "ariaLabel". The strip draws no caption, so draw the same words as visible text beside it, and never pass a name of white space alone, which leaves the group with no name. tints is an array of tint keys naming the swatches drawn, in its order, each once: a key outside Fabricate’s ten, a repeat, a value that is not a string, 'Rose' and '--fab-tag-rose' among them, is dropped; absent, not an array, or naming none of the ten, it draws all ten in Fabricate’s order. labels is an object of final display text keyed by tint key, as { rose: 'Rose' }, which a swatch draws as its aria-label and as the title the pointer shows; an entry that is absent, not a string or white space alone draws nothing. Each swatch is named by its tint’s text in labels, or else by Fabricate’s own name for the tint, which is English and is not localized. A swatch has no text of its own, so its name is all a reader hears of it: in a world whose language is not English pass labels for every tint you draw, in the world’s language. An entry for a tint the strip does not draw names nothing. The strip draws no No-colour radio, because allowNone is not published, so once a swatch is checked the strip offers no way back to none; where your record may hold no colour, draw that choice as a control of your own beside it.
- The group is one Tab stop: Tab reaches the checked swatch, or the first swatch where none is checked, and Tab again leaves the group.
- ArrowRight and ArrowDown move focus to the next swatch and ArrowLeft and ArrowUp to the previous, wrapping at each end, along the order the swatches are drawn in and never to the row below; under
direction: rtl, read from the focused swatch, ArrowLeft moves to the next and ArrowRight to the previous, and ArrowUp and ArrowDown keep their order. - Home moves focus to the first swatch and End to the last; each of these keys also chooses the swatch it moves to, as a radio group does, and is not passed on, and an arrow key held with Alt, Control or Meta is left to the browser.
- Every swatch carries
data-keyboard-focus, so Foundry runs no keybinding, a canvas pan among them, while one holds focus. - An
updatekeeps every swatch that is still drawn, so focus stays where it is while the check moves;destroyremoves them, so where a swatch holds focus, move focus first.
The checked swatch is marked by a two-tone ring and by aria-checked, so colour never carries the choice alone: a 2px inset ring drawn inside its colour in --fab-biome-icon-foreground, which clears 3:1 on every tint in all seven palettes, 3.09:1 at the least, and a 2px outer ring in --fab-text drawn in the swatch’s own padding, which clears 3:1 on the strip’s ground, so on any tint and ground one of the two does. The choice’s non-visual carrier is aria-checked, and its visual mark is that dark ring, which is measured against the swatch’s colour, not the ground around it, so on a near-black ground it reads only against the tint. Keyboard focus draws the 2px accent outline inset by 2px on the swatch’s edge, clear of its colour, so it shows beside the checked ring; it clears 3:1 over --fab-bg-0, --fab-bg-1, --fab-surface and --fab-bg-2 in all seven palettes, 5.19:1 at the least. Under the pointer a swatch draws the same accent as a 2px ring 1px clear outside its 1px border edge, never a fill, so a swatch’s colour never changes; it draws in the frame the pointer arrives, under either prefers-reduced-motion setting, as the focus outline does. Each swatch’s 1px --fab-border edge carries no state outside forced colours. A keyboard-focused swatch under the pointer draws both marks at once, the focus outline inside its edge and the hover ring outside it, 1px apart. Under forced colours each swatch keeps its tint and the checked ring, because the tint is the value itself, and the checked swatch’s edge takes the system Highlight colour. A strip is drawn the same in the Manager, the player window and, under the standalone style root, your own window or dialog, and it is no wider than target. TintSwatches takes no rest props, so a data-* prop is refused with "<key>" is not a prop of TintSwatches. A Fabricate that predates it does not list TintSwatches in components, describe('TintSwatches') answers null, and mount refuses it with "TintSwatches" is not published, so draw your own swatches there. The role, names and checked state are read from Chromium’s accessibility tree and the keys pressed in Chromium; no screen reader was run. Its cell, gap and corner figures beyond what this section states, its classes and data-manager-color-* hooks, its leading No-colour radio and the noneLabel, noneChecked and onClear props that draw it for Fabricate’s own editors are private, so a noneLabel or an onClear is refused with "<key>" is not a prop of TintSwatches.
A worked strip follows: the colour of one of your activities, beside a caption of your own.
// After `load(['TintSwatches'])` has resolved and `fabricate.ready` has fired.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the strip describes none: draw your own swatches there.
if (!fabUi?.describe?.('TintSwatches')) return;
// Your caption above `target`: <span>Activity colour</span>.
const TINTS = ['sage', 'rose', 'butter', 'azure'];
let colour = activity.colour ?? 'sage';
const props = () => ({
value: colour,
ariaLabel: game.i18n.localize('ACME.ActivityColour'), // The words your caption draws.
tints: TINTS,
labels: Object.fromEntries(TINTS.map((tint) => [tint, game.i18n.localize(`ACME.Tint.${tint}`)])),
onChange: (next) => {
colour = next;
activity.colour = colour; // Your own state first.
strip.update(props()); // Every prop again, with the new `value`.
},
});
const strip = fabUi.mount('TintSwatches', { target, props: props() });
The descriptor
api.ui is a frozen { schemaVersion: 1, components, describe, mount, load, mountMany }. components lists the published names in publication order, and a new name is appended, never interleaved. describe(name) returns a frozen { version, props, rest, root, overlays }, where each prop is { kind, required, requiredWhen? }, rest says whether the component takes data-* attributes, root is the Fabricate ancestor its target needs (it does not say whether Fabricate draws the component under the standalone style root) and overlays says whether it opens an overlay, described under Overlays; it returns null for a name that is not published. A prop’s kind is data, text, slot, callback, aria or value. requiredWhen is present only where a prop is required while another is truthy, and names that other prop; required is then false. A prop describe reports required may still be empty where its component’s section says so, as Chip’s children in its icon-only form; describe does not state that. A data prop takes plain data, and the component receives a copy. A text prop takes a string, which Fabricate draws as plain text inside the component and never reads as HTML; the element Fabricate wraps it in is private. A text prop that is undefined, absent or '' is omitted, so the component’s own fallback applies; a required one refuses ''. A slot prop is a content slot, a place where the component draws your own content. It takes true to request the content slot and false, undefined or absence to omit it, and it is never required. A callback prop takes a function, and undefined or absence omits it, so the component’s own default applies. A required callback prop refuses absence and undefined with <name> requires a non-empty "<key>", and one whose requiredWhen names a prop that is truthy refuses them with <name> requires a non-empty "<key>" when "<other>" is truthy; either refuses any value that is not a function, '' included, with "<key>" must be a function. The component holds one stable stand-in for your function for the life of the mount, so an update that passes another function re-renders nothing and the next call reaches the newest function. Fabricate calls your function with the arguments the component’s section states, or, for a value prop’s on<Key>Change, (next, previous), in that order, and with nothing else: each is a plain copy, and no event, DOM node or Fabricate object is passed. The call is synchronous, inside the user’s event, after the component has finished its own state change; a published callback is never called while Fabricate renders or runs an effect. It runs under Fabricate’s untrack, which covers Fabricate’s runtime only, so if you are called back inside an effect of your own, untrack your own reads. Your function may call update or destroy on its own handle, or mount, before it returns; an update made there is drawn on Fabricate’s next flush, except that a value it changes is drawn before the call returns. After destroy, a fault, or an update that omits the prop, Fabricate does not call the function again; a required prop cannot be omitted, so an update that omits it throws and the earlier function still answers. Detect a callback prop with describe(name).props[key]?.kind === 'callback', because a Fabricate that predates it refuses the prop. An aria prop is an ARIA attribute Fabricate writes, under the prop’s own name, on the control the component’s section names; the component declares no prop of that name. It takes a string, a number or a boolean and writes it as the attribute’s value, so false writes "false". undefined or absence writes no attribute. Anything else throws "<key>" must be a string, number or boolean. An aria prop is never required. An update that changes the prop’s value writes it on the same element, and one that omits the prop removes the attribute. Fabricate writes the attribute only when the value differs from the one it last wrote, so it puts back nothing other code removed or replaced. Fabricate checks no value against the attribute’s own set: the component’s section states the accepted values, and any other is private. Detect an aria prop with describe(name).props[key]?.kind === 'aria', because a Fabricate that predates it refuses the prop. A camel-case prop is one the component interprets, and a hyphenated aria-* prop is an attribute Fabricate writes under that name; a control’s name is carried by the prop its section names, and by the text that an aria-labelledby prop its section names points at. A value prop is a value the component binds and may change itself, such as the text of a search field. It takes a string, a number, a boolean or null, and anything else throws "<key>" must be a string, number, boolean or null; undefined or absence means you pass none, so the mount starts at the component’s own initial value, which its section states. A value prop is never required. Each value prop brings an optional callback prop named on, the prop’s name with its first letter upper-cased, then Change: query brings onQueryChange. describe lists the value prop as { kind: 'value', required: false } and directly after it that callback as { kind: 'callback', required: false }. Fabricate calls it with (next, previous) only when the component changes the value itself, once per change, and never when the two are the same by Object.is; mount and update never call it. A component that clears a value to undefined changes it to its initial value, so next is never undefined. Inside the call, handle.value(key) already answers next. A throw from it is reported as any callback’s is, under Mounting, updating and destroying. Inside that call, an update with the same value changes nothing, and one with another value is drawn before the call returns and wins, with no second call, so you can reject, revert or transform what the user typed; one made later shows on the next flush, so the user briefly sees their own text first. A replaced value moves a text input’s caret to the end and ends any IME composition in progress. handle.value(key) reads a value prop’s current value, and answers undefined for any other prop and after destroy or a fault; null is a legal value. Detect both before you rely on them, because a Fabricate that predates a value prop refuses it:
const bound = fabUi.describe(name)?.props[key]?.kind === 'value';
const readable = typeof handle.value === 'function'; // `handle` is what `fabUi.mount(...)` returned.
An ARIA attribute is published only as an aria prop a component’s section names. A state the component shows (aria-pressed, aria-checked, aria-selected, aria-current, aria-disabled), aria-hidden, a live-region attribute (aria-live, aria-atomic, aria-relevant) and a reference that re-parents content (aria-owns, aria-activedescendant, aria-flowto) are never published as one. A name source (aria-label, aria-labelledby) and any other aria-* name, aria-controls, aria-haspopup and aria-busy among them, are not published at version 1 unless a component’s section names the prop (StatusToggle’s section names aria-labelledby); publishing one later is additive. mount(name, options) draws a component and load(names) loads its code first; both are described under Mounting, updating and destroying. mountMany(name, items) draws one component into several targets, as Mounting several at once describes. typeof fabUi.load === 'function' also says that mount honours onFault. Treat an unknown name, member, prop kind or root as absent, and never assume the list is closed: adding a component, an optional prop, a descriptor member, a handle method or a prop kind, or widening a component’s root, is additive, and so is adding a value to a prop’s accepted values where the prop’s section states that a value outside its accepted values draws as unset, as Medallion’s tone and ink do: a Fabricate that predates the value draws the unset render and refuses nothing. Where a section says nothing of a value outside a prop’s accepted values, or calls what is drawn for it private, pass only the values that section lists. Narrowing a component’s root is a breaking change. The rest names a component reserves are fixed for its version, and reserving another is a narrowing; describe does not state them, so read them from the component’s section. A breaking change to one component bumps that component’s version, keeps the old shape as a deprecated delegate for at least one minor release, and is announced in the release notes; schemaVersion changes only with the seam’s own shape.
Mounting, updating and destroying
mount(name, { target, props = {}, onFault, overlayHost }) is synchronous and returns with the DOM in place; effects and the component’s scoped stylesheet apply on Fabricate’s next microtask flush. It renders on Fabricate’s own Svelte runtime, so a companion’s own Svelte version does not have to match it; Fabricate’s premium companion builds against Svelte 5.56 or later. It returns a frozen { update(props), destroy(), slot(key), value(key) }. Fabricate draws the component’s elements inside target and attaches no shadow root of its own, so they share target’s root node and an id reference resolves across the mount in either direction; the one exception is an open overlay’s panel, which is drawn in its host.
targetmust be an element (checked bynodeType, so an element in a Foundry 14 detached window is accepted), must be empty, and must not hold a live mount. A component whose root is notanyalso needs that Fabricate ancestor abovetarget: otherwisemountthrows<name> needs a Fabricate window ancestoror<name> needs a Fabricate manager ancestor, before it claims the target. A Fabricate root is a.fabricateancestor that is not a standalone style root. A component Fabricate draws under the standalone style root throws<name> cannot be drawn in a shadow root, also before it claims the target, wheretargethas no Fabricate root and its root node is a shadow root.propsmust be a plain object of the component’s published props, holding only data: primitives, plain objects and arrays, with a function only as a callback prop’s value and no cycle. A function anywhere else, at any depth, throws"<key>" must not hold a function, naming the prop that holds it. Acallbackprop holds a function, and anything else there throws"<key>" must be a function. Atextprop holds a string, and anything else there throws"<key>" must be a string. Aslotprop holdstrueorfalse, and anything else there throws"<key>" is a slot and takes true or false. A component whoserestistruealso takesdata-*attributes holding a string, number or boolean, and any other rest key throws"<key>" is not a data attribute. Where a component’s section says its rest lands on a control,data-keyboard-focus,data-action,data-cursor,data-tooltip, every name that startsdata-tooltip-, and the two names Fabricate’s own stylesheet reads off its buttons,data-validation-focusedanddata-essence-sort-direction, throw"<key>" is reserved on <name>. Where it also says that control carries Foundry’s tooltip,data-lockedthrows the same. Anariaprop holds a string, a number or a boolean, and anything else there throws"<key>" must be a string, number or boolean. Avalueprop holds a string, a number, a boolean ornull, and anything else there throws"<key>" must be a string, number, boolean or null. A name that must contain a component’s visible text, asButton’sariaLabelitschildren, is dropped when it is blank or not a string, so it writes no name, and throws"<key>" must contain the text of "<other>" ("<text>" is not in "<name>")when it holds a non-blank string that does not contain that text’s words as one run of whole words. For aSegmentedControloption’sariaLabeland itslabel,<key>and<other>name the option, asoptions[<index>].ariaLabelandoptions[<index>].label.onFaultis optional, and is described with faults below.overlayHostis optional, and is described under Overlays. When it is passed, on any component, it must be an element oftarget’s own document (checked bynodeType), ormountthrowsoverlayHost must be an element in the target's document, after the root check and before it claims the target.- Props are copied when you pass them, so mutating your object afterwards changes nothing.
update(props)replaces the props, so an omitted prop falls back to the component’s default, and nothing remounts; an omitted orundefinedvalue prop keeps its current value instead. It is atomic: when it throws, the previous props stay rendered. It returnstrueonce accepted andfalseafterdestroyor a fault.destroy()is idempotent, never throws, releases the target, and closes every overlay the mount holds open. Call it from your own cleanup, from an ApplicationV2_preCloseor_onClose(or beforesuper.close), and on any re-render that replaces the target or its ancestors (in_preRender, or in_onRenderbefore mounting again), because DialogV2 and Handlebars_replaceHTMLreplace their content on render;destroyworks whether or nottargetis still in the document. It is safe after a fault, and still expected there. A mount that is never destroyed leaks for the life of the page, and keeps its slot elements, their content and every nested mount with it.slot(key)returns the content slot’s element, the same one for the life of the mount once it has been requested. It returnsnullfor an unknown key, for a content slot never requested, and afterdestroyor a fault. The element is a<div>, or a<span>where the component draws the content slot inside phrasing content; each component’s section says which. It is created bytarget.ownerDocumentand carriesdisplay: contentsand no other attribute, so its children lay out as the component’s own would. The element Fabricate holds it in is private.value(key)returns a value prop’s current value, andundefinedfor any other prop and afterdestroyor a fault.
mount and update throw a TypeError whose message starts with Fabricate | published components: for a malformed request, and mount throws a plain Error ending not registered if Fabricate’s runtime has not loaded. A mount before the fabricate.ready hook has fired throws mount before ready, a mount of a lazy component before load has resolved for it throws "<name>" is not loaded, and a required prop that is absent, or '' (or white space alone where a contains key names it) where it is not a callback prop, throws <name> requires a non-empty "<key>", and '' on a callback prop throws "<key>" must be a function. A required ariaLabel, label, title or legend prop that no contains prop names and that states no waivedBy or waivedWhen throws <name> requires a non-blank string "<key>" when it holds a non-string or white space alone. A prop whose requiredWhen names a truthy prop is refused the same way while that prop is truthy, with <name> requires a non-empty "<key>" when "<other>" is truthy; with several, the first prop describe lists is named. A required prop that its component’s section lets be empty while other props hold text, as Chip’s children beside icon and ariaLabel, is refused with <name> requires a non-blank "<other>" when "<key>" is empty while only some of them do, naming the first that does not. A required prop that its component’s section lets be empty while another prop is true, as SelectionCheckbox’s label and onChange beside decorative: true, may be absent, or '' where it is not a callback prop, while that prop is exactly true, and is refused as any required prop is otherwise; describe still reports it required. The full list of fixed messages is in the ui-extension-points specification’s Published UI Components section.
Fill a content slot by mounting a component of your own into its element, or by appending an element you own. In a <span> content slot what you append is phrasing content, a <span> for a mount target. Style and attribute your own elements and never the slot element: a class, role, tabindex or ARIA attribute on it is unsupported. A child of a content slot that draws nothing still takes the host’s gap. A host spaces a content slot’s children by gap, except where its section states it draws them in normal flow, as Well and ListRow’s aside do; you then fill that slot with one element of your own that lays out its content. Focusable content you draw in a content slot is yours to mark data-keyboard-focus="true", except in ListRow’s leading, badges, meta and aside, where you draw none, as its section states. A <button> you draw there states type="button": an untyped button submits the <form> it is in, and in Foundry that closes a DialogV2 and saves a document sheet. Put data-action on nothing you draw there: the window dispatches a click on any data-action inside it, close, tab and toggleControls in every window and each button’s name in a DialogV2. Fabricate attaches the slot element wherever the component draws that content slot, and detaches it with its contents intact while it does not; a detached element is disconnected, and your components, effects, listeners and bound values inside it keep running, though a component with an overlay mounted in it closes its open panel, as Overlays states. Each detach and attach is a DOM removal and insertion, so the browser resets what it resets on those: an <iframe> reloads, playing media pauses, focus and scroll positions inside the slot element are lost, CSS animations restart, and a custom element receives disconnectedCallback and connectedCallback. That happens when the content slot is omitted and requested again, when an update makes the component replace the element holding it, and when a Foundry 14 window is detached or re-attached, which also moves the content to another document.
A published component may itself be mounted in a slot element, and one destroy then ends both:
// After `load(['InspectorCard', 'Kicker'])` has resolved and `fabricate.ready` has fired.
const card = fabUi.mount('InspectorCard', { target, props: { children: true } });
const nested = [
['Kicker', { children: 'Renown' }],
['Meter', { label: 'Renown', value: 3, max: 5, valueText: '3 of 5 renown' }],
].map(([name, props]) => {
const element = target.ownerDocument.createElement('div');
card.slot('children').append(element); // Append first: a root other than `any` is judged from here.
return fabUi.mount(name, { target: element, props });
});
card.destroy(); // Ends the kicker and the meter, then the card.
destroy first destroys every live published mount inside its slot elements, then detaches each slot element with its remaining children untouched. The nested handles are dead from then on: update answers false and destroy does nothing, so drop them with the card’s handle, in onFault as well. Fabricate never empties a slot element and never calls into your runtime, so content you drew there with your own runtime is yours to tear down, before destroy. On every path that ends such a mount, unmount what you drew in its content slot with your own runtime, then call destroy on the outermost handle, which ends every published mount nested in its slot elements. A navigation provider does both in the cleanup its mount returned, which Fabricate calls while the target is still connected and before requestRemount clears it. A host that replaces its content on every render (DialogV2, a Handlebars part) does both on each re-render and mounts again in _onRender.
If the component faults while rendering, updating or in an effect, Fabricate logs Fabricate | Published component render failed: with the name and the error, empties target, and the handle goes inert. The report, and update answering false, arrive after a microtask, never inside the mount or update call that caused the fault. Any fallback copy is yours to draw. A teardown that throws while Fabricate unmounts is reported the same way, a microtask later. After such a teardown the target may still hold a node of Fabricate’s, so empty it before mounting there again. A cleanup that throws while Fabricate tears a faulted component down is reported as that mount’s fault, once, with the cleanup’s error. A fault ends nested published mounts, detaches slot elements and closes open overlays as destroy does; a nested mount is destroyed, not faulted, so its own onFault is not called. Keep your own reference to content you drew in a content slot and tear it down from onFault, because handle.slot answers null from then on.
Pass onFault(error) to mount to be told of that fault. It is called once, in a microtask after Fabricate has torn its own content down, and never inside mount, update or destroy. By then the claim is released and target is empty, so you may mount into it from onFault. Do not mount the same input again unconditionally: a fault that repeats calls onFault again in a later microtask of the same task, so the page cannot paint in between. A throw from onFault is reported as a render failure under the component’s name and goes no further; a Promise it returns is ignored. Without onFault, a fault is discovered only when update answers false.
const handle = fabUi.mount('Kicker', {
target,
props: { children: 'Standing' },
onFault: () => {
target.textContent = 'Standing'; // Your own fallback, drawn into the emptied target.
},
});
What a callback prop’s function returns is ignored. A throw, or the rejection of a Promise it returns, is logged as Fabricate | Published component callback failed: with the name, the prop and the error, and goes no further: the mount stays live, it is not a fault, and onFault is not called. A refusal that an update throws inside your function is reported the same way unless you catch it.
load(names) takes an array of published names and returns a Promise. A value that is not an array is read as one name. It never throws synchronously, and is callable as soon as api.ui is readable, before fabricate.ready. api.ui is readable from setup onward; in your own init it may not be bound yet. It resolves undefined once every named component’s code is loaded: at once, on the next microtask, for a component Fabricate loads with its own entry script, and once its code is fetched for a lazy one. It rejects with a TypeError ending "<name>" is not published for a name that is not published, before it fetches anything, and with the browser’s own error when a lazy component’s code cannot be fetched. It does not wait for fabricate.ready, so mount still throws mount before ready until that hook has fired. TierTrack, Avatar, Medallion, FillBar, Meter, BandedBar, StatBox and InfoStrip never need it; Kicker, Chip, Rail, InspectorCard, EmptyState, Notice, Button, StatusToggle, Stepper, SearchField, Select, StageBars, Field, Well, Callout, IconButton, EditorTabs, RadioCardGroup, SegmentedControl, Pagination, IconPicker, ActionMenu, Modal, ListRow, ToggleCard, SelectionCheckbox, Disclosure, Typeahead, Popover and TintSwatches were published with load, so call it for each before mounting. Rail is lazy: Fabricate’s entry script does not carry its code, load fetches it, and until load(['Rail']) has resolved, mount('Rail', …) throws "Rail" is not loaded and draws nothing. A load you do not await still starts the fetch, but mount refuses the component until it has resolved, and a rejection nothing handles is an unhandled rejection. A lazy component’s code is fetched once per page session: calls made together share the one fetch, and a fetch that failed is not retried, so every later load naming it rejects with the same error and mount keeps refusing it until the user reloads. Fabricate draws no pending state and no error state for a load, so draw your own until load settles and, when it rejects, your own error state, announced through your own live region. When the fetch failed because the browser runs a stale copy of Fabricate, Fabricate also shows its reload notice, shared with the Manager’s so one shows at a time, and at most once per page session. A failure before Foundry has created its notifications, which a load made in setup can meet, shows that notice when Foundry’s ready hook fires. Once loaded, a lazy component mounts, draws and behaves exactly as it would if Fabricate loaded it with its entry script. Call load once, keep the promise, and mount only after it has resolved and Fabricate is ready:
let published = null;
Hooks.once('setup', () => {
const fabUi = game.fabricate?.api?.ui;
// Absent on a Fabricate that predates `load`, where `mount` also ignores `onFault`.
// Settled to a boolean here: a name this Fabricate does not publish must not reject in a render.
published = fabUi?.load?.(['Kicker', 'Chip']).then(() => true, () => false) ?? null;
});
// In your ApplicationV2, once `fabricate.ready` has fired:
async _onRender(context, options) {
await super._onRender(context, options);
if (!(await published)) return;
// Mount here, destroying any earlier handle first.
}
An ApplicationV2 _onRender may await the promise, but handle its rejection where you keep it: Foundry awaits _onRender, so a rejection there fails the render and skips the render hooks. A navigation provider’s mount callback may not, because it returns synchronously, so content drawn there mounts its published components when the kept promise settles.
Mounting several at once
mountMany(name, items) draws one component into several targets in one call, such as a Meter in each row of a list. items is an array, and each item is what you would pass mount as its options, { target, props, onFault, overlayHost }. Each item has its own onFault and overlayHost, and nothing is shared across the call. It returns a frozen array of handles, one for each item and in the same order, and each handle is the one mount would have returned. An empty array returns a frozen empty array. Detect it with typeof fabUi.mountMany === 'function'.
#meters = [];
// In your ApplicationV2, once `fabricate.ready` has fired. `Meter` never needs `load`.
// `#party` is your own list.
_onRender(context, options) {
super._onRender(context, options);
const fabUi = game.fabricate?.api?.ui;
if (typeof fabUi?.mountMany !== 'function') return;
for (const handle of this.#meters) handle.destroy(); // A re-render replaced the old targets.
this.#meters = fabUi.mountMany(
'Meter',
this.#party.map((member) => ({
target: this.element.querySelector(`[data-hp-meter="${member.id}"]`), // Empty, and yours.
props: {
label: `${member.name}'s hit points`,
value: member.hp,
max: member.maxHp,
valueText: `${member.hp} of ${member.maxHp} hit points`,
},
}))
);
}
async _preClose(options) {
for (const handle of this.#meters) handle.destroy(); // Each handle is destroyed on its own.
await super._preClose(options);
}
mountMany checks the whole call before it draws anything, so a refused call draws nothing and you correct it and call again. The first problem it finds is the one it throws, with the message mount would give. It checks the name first, as mount does, so it throws not registered, mount before ready, "<name>" is not published, or, for a lazy component before load has resolved for it, "<name>" is not loaded. It then throws items must be an array for anything that is not an array, a single item included, because it never reads one item as a list of one. It reads the length of items once and follows no iterator, so an item added while the call is checked is not drawn. It then checks each item in order exactly as mount checks its options, apart from the stale-mount case below. An item that is not an object, or a hole in the array, has no target, so it throws target must be an element. Two items that name the same target throw target already holds a published component. The check ends no earlier mount. A mount whose content you cleared without destroying it is ended only when its target’s item is drawn. If that mount left a node in the target, mountMany throws target must be empty, where mount would end that mount first and draw. Destroy that mount’s handle or empty the target before you call. A target you mean to place inside the content slot of another item of the same call is not inside it yet. A component that needs a Fabricate ancestor refuses that target, so mount the outer items first and the nested ones in a later call. A stale mount can also have a content slot that holds a later item’s target, when an earlier item’s draw ends that stale mount. The later item is still drawn, into the detached slot, where separate mount calls would refuse it for a component that needs a Fabricate ancestor. A component Fabricate draws under the standalone style root is drawn there with no standalone style root, where separate mount calls would write one. Mount nested targets in a later call. Once the call has been checked, a fault while one item renders is that item’s own. Its handle is inert, only its own onFault is called, and the other mounts are drawn and stay live. There is no call that destroys them all. Destroying one handle leaves the others live, so destroy each handle on every path that ends its mount.
Overlays
A component whose describe(name).overlays is true opens an overlay: a panel it draws outside target while it is open, such as a list, a menu or a dialog. Select is the first, and its section states what its list draws. IconPicker is the second: its list and its query field are the overlay, and its section states what they draw. ActionMenu is the third: its menu is the overlay, and its section states what it draws. Modal is the fourth: its dialog is the overlay, and its section states what it draws. Typeahead is the fifth: its suggestion list is the overlay, and its section states what the list draws. Popover is the sixth: its panel is the overlay, and its section states what it draws. mount ignores an option it does not know, so overlays === true is also your signal that overlayHost is honoured. Each time an overlay opens, Fabricate picks where to draw it, from target’s own document at that moment:
- the
overlayHostelement you passed, while it is connected and intarget’s document; - else the nearest Fabricate window root above
target(.fabricate-manager,.fabricate-app), or a Fabricate standalone layer, unless it lies outside the top-layer element step 3 names; - else, where the element the panel is placed against or
targetis inside an element in the browser’s top layer, a<dialog>opened withshowModal()as a DialogV2 withmodal: trueis, a fullscreen element or an openpopover, a standalone layer Fabricate keeps inside the nearest such element while any overlay is open on it, themed as the one below, so the panel is that element’s descendant: it is drawn above the page with it, it is not inert, it takes the pointer and it is in the accessibility tree; - else a standalone layer Fabricate keeps on
target.ownerDocument.bodywhile any overlay in that document is open on it, themed from the nearest ancestor oftargetinside its<html>that carriesdata-fabricate-theme, else from Fabricate’s own document, copied when the layer is made.
Give overlayHost a position other than static with a size, because it is the panel’s containing block and the origin its coordinates are measured from; it need not be connected when you mount. A Modal dialog is position: fixed, so its host’s position does not make the host its containing block, as its section states. A component’s section may narrow where overlayHost sits, and Select’s, IconPicker’s, ActionMenu’s, Modal’s and Typeahead’s do: keep it inside the same Fabricate window as target, and pass none where target has no Fabricate root. Popover accepts a host anywhere in target’s document, and its section states what one outside every Fabricate window changes. The standalone layer Fabricate keeps for your panels spans the viewport of its window, the box they are measured against, and takes no pointer, so a panel on it is placed where it was measured and the page around the panel still takes input. Unless the panel’s own section says it stops it, a press or a key in a panel on the standalone layer on <body> bubbles to the page’s body and document and never through your window, target or any element of yours, so a listener of yours there hears none of it, and one in a panel on a layer inside a top-layer element bubbles through that element and its ancestors first, outside any <form> in it, so a listener of yours on your dialog element hears it; Escape pressed in it reaches Foundry’s dismiss keybinding, which closes no window where the panel’s section says so, as for an IconPicker list or an ActionMenu menu. The panel is drawn inside a display: contents element Fabricate mounts on its own runtime, so the panel’s own handlers run in whichever document holds it, a Foundry 14 detached window included. Where its host is the standalone layer, that element states pointer-events: auto and a Fabricate window’s typeface and size, var(--font-body, var(--font-primary, sans-serif)) and var(--font-size-14). That element, the panel and everything in it are private: select none of it. The standalone layer, its class and its data-fabricate-theme copy are private too. A standalone style root is a different element, is never an overlay host, and holds no panel. The panel is not clipped by target’s overflow, because it is drawn in its host; place overlayHost where it is not clipped. An overlayHost you pass outside a modal <dialog> that holds target still wins, and a panel drawn there is inert, so in such a dialog pass one inside it, or none. In a <dialog> opened with showModal(), Chromium closes the dialog on an Escape whose default nothing prevents: a Popover, a Typeahead, a Select, an IconPicker and an ActionMenu prevent the Escape that closes their panel, so the dialog stays open and a second Escape, with no panel open, closes it. An overlay listens for outside presses, Escape and scrolls on the document that holds it, and an open Select, IconPicker, ActionMenu or Typeahead watches that document for its target leaving it; it listens for resizes, and a Modal dialog for its record of each Escape, on that document’s window. An overlay whose document has no window stays closed. An overlay opened from a published mount nested in another mount’s content slot, or from inside another overlay’s panel, takes the host chain of that mount or panel. destroy and a fault close every open overlay and remove its panel, its element and a standalone layer nothing else uses. The panel of a component with an overlay, a Select, an IconPicker, an ActionMenu or a Typeahead, also closes when its target is disconnected while your mount is live, as when an update of the component whose content slot holds your mount detaches the slot. Its panel and its element are removed, focus is not moved, so focus left in the panel goes to the page, and the component calls no callback. A target that is removed and inserted again within one run of script keeps its panel open. A panel stays watched in the document it opened in, so after a Foundry 14 move a detach in the new window does not close it. A target inside a shadow root closes its panel when that root’s host leaves the document, and not when the removal happens inside the shadow root. A Modal dialog closes the same way while its target is disconnected, as when an update of another Modal whose content slot holds it detaches the slot: the dialog is removed and calls no callback, and because its open still stands it is drawn again once target is attached, watched in the document it opened in as a panel is. On Foundry 14 Fabricate does not follow a mount from one window to another, so destroy it and mount again in _onDetach and _onAttach; that destroy closes any open overlay. Foundry moves an application rendered with renderChild into its parent’s detached window without calling its _onDetach, and an overlay opened after any move is placed and heard in the new window.
// A positioned element of your own window; a Fabricate that predates overlays ignores it.
const overlayHost = this.element.querySelector('.my-module-overlay-host');
const handle = fabUi.mount(name, { target, props, overlayHost });
Ownership and theme
You own the placement of target: size it as a block-level container, write nothing inside it while it is mounted except inside a slot element, and style only the target’s own box. A published component inherits from target every inherited text property its own rules do not state, so set none on target. .fab-* and manager-* classes and svelte-* hashes are private and may change in any release: select none of them, and write no manager-* class on an element you own, target included. Never write fabricate, fabricate-app or fabricate-manager on an element you own. A data-* name Fabricate writes is private as its classes are: pass only rest names that carry your own module id, because Fabricate styles some of its own elements by a data-* hook. Pass final display text: a string you supply is rendered verbatim and never treated as a localization key. Localise it first with your own game.i18n; Fabricate adds no default copy or accessible name but the glyph names an IconPicker draws and the tint names a TintSwatches draws where you pass no labels, as each section states. A published component is not a live region unless its section says it is. Every component states a root, the Fabricate ancestor its target needs. A component whose root is any resolves its tokens from :root[data-fabricate-theme] and its own stylesheet, so it needs no Fabricate ancestor. The exception is a component Fabricate draws under the standalone style root, whose tokens resolve from that element’s data-fabricate-theme. A fabricate component needs a Fabricate root, a .fabricate ancestor that is not a standalone style root, which Fabricate’s window frames carry (the player window, the Manager and the interactable windows), so both extension targets have it. A manager component needs a .fabricate-manager ancestor, the Manager’s root inside its frame. Every component published at version 1 states any, so fabricate and manager are values describe may return for a later component, and no mount you make today is refused for a missing Fabricate ancestor. mount decides it by class, with target.closest, at mount only, and judges a target inside a slot element that is not attached from the mount that owns that element. Your own window, a chat message and another module’s sheet carry no Fabricate root, so they host any components only, and the twenty-two components the standalone style root section names are drawn there under one, Stepper only where target is in no <form>. Mount a component after target is attached to its final document. In an ApplicationV2, mount in _onRender, never in _renderHTML. A mount into an attached target in its final document is styled, including in a Foundry 14 detached window. A later move between windows is not carried to a mount, and a theme change made after a window detached does not reach that window. A companion that owns the ApplicationV2 re-mounts in _onDetach and _onAttach; content inside a Fabricate window has no such signal. Mount at the composite level, on stable keyed elements, and reuse a mount through update rather than mounting per row.
A published component draws a control only where its section says so, and each control is a native element: a <button type="button">, which only a Button whose type says so draws as another type, an <input>, a <select> or a <textarea>.
- A control never submits a
<form>it is mounted in, except that aButtonwhosetypeissubmitsubmits it as its section states, and a text-like<input>submits it on Enter as implicit submission does (through the form’s first submit button, or alone where it is the form’s only text field) and fires a bubblingchangethat a form withsubmitOnChangesubmits on, and aRadioCardGrouporSegmentedControlradio, or aPaginationpage-size radio, fires a bubblingchangeon each choice that such a form submits on too; in Foundry a submit closes a DialogV2 and saves an editable document sheet. That exception reaches a radio and a number input too where the form has a submit button: Enter there submits the form, as on a text-like input. - A
resetof the<form>a control is in, aButtonwhosetypeisresetmaking one, changes what it shows and reports nothing, and anupdatethat passes the same value does not redraw it, so reset no form a published control is in, or destroy the control and mount it again (read from Svelte 5.56 source, not run). - A
<button>carriesdata-keyboard-focus="true"on itself, so Foundry runs none of its keybindings while it holds focus; an<input>, a<select>and a<textarea>hold them off without it. Where a component’s rest lands on the control itself,data-keyboard-focusis refused, so you cannot replace it. - A button is pressed by pointer, Enter or Space, as the platform presses a native button, and handles no other key itself unless its section names the key, as the
EditorTabsandTintSwatchessections do: akeydownlistener of yours abovetargetstill receives every key, except from aSelectorIconPickertrigger, which stops each key but Tab, with or without Shift, and anActionMenutrigger, which stops ArrowDown and ArrowUp, as each section states, and Foundry’s keybindings stay held off as the bullet above states. A key pressed in an openModaldialog bubbles to the dialog’s host and its ancestors, never through theModal’s owntarget, and Escape there stops at the dialog, and withtrapFocusevery key stops at the document, as its section states. A pointer press acts on release, as aclick, never on pointer down, so a pointer that leaves the control before release cancels it. Enter presses on key down and again on each repeat while held, except on thePaginationarrow or page-size radio, or theActionMenutrigger or item, Fabricate has moved focus to, as each section states, and Space on release. In an ApplicationV1DialogEnter presses no control: that dialog takes Enter anywhere inside it and submits its default button, so a control there is pressed by pointer or Space. - A control consumes only the keys the platform gives its native element, and its section names any other. Tab moves focus as the browser does, except in an open
ActionMenumenu, where it closes the menu and returns focus to the trigger, a published behaviour kept so your Tab handling does not change, and in an openIconPickerlist’s query field, where it closes the list and moves focus on from, or back to, the trigger, as each section states, and Escape still closes a DialogV2 while a control holds focus, because a DialogV2 listens for Escape on its own element, except while aSelectorIconPickertrigger holds focus, because it stops Escape, as each section states. In any other window Escape closes nothing while a control holds focus, because closing a window on Escape is one of the keybindings held off; an open ApplicationV1Dialogstill closes, because it listens for Escape on the document, unless the key is pressed in an openModaldialog, which stops it at the dialog unless an expanded control there keeps it, and asks you to close thatModal, as its section states. An open ApplicationV1Dialogin the main window takes a Tab pressed anywhere outside thatDialogand moves focus to its own button. - A control draws its own mark for keyboard focus where the component’s
rootisanyand Fabricate does not draw it under the standalone style root; otherwise it shows the Fabricate window’s accent ring, 2px wide, at the offset the component’s section states, except anActionMenuitem, whose 1px accent ring is drawn inside its edge, aListRowbutton, whose 2px ring is drawn inside the row’s edge, and aSearchField, whose shell’s 1px border takes the accent while its input draws no ring, as each section states. A text-like input or textarea you draw in aField’s content slot shows the field’s 1px accent ring, inset 1px, as that section states. Where a component’s rest lands on the control itself,data-validation-focusedanddata-essence-sort-directionare refused: they are names Fabricate’s own stylesheet reads off its own buttons, whose effect is private, and the first, under a Fabricate root, draws the keyboard ring on a control that does not hold focus. - A control’s accessible name is text you pass through a prop its section names, or your own visible text that an
ariaprop its section names points at, and Fabricate supplies none, except anIconPickerrow, named by its glyph’slabel, the caption anIconPickertrigger adds toariaLabel, aDisclosurebutton, which is named by the text you draw in itsheadslot, and aTintSwatchesswatch, which is named by Fabricate’s name for its tint wherelabelsnames it not, as each section states. Where a prop carries the name,aria-labelis refused, and so isaria-labelledbyunless the component’s section names it as anariaprop. A section namesaria-labelledbyonly for a control that draws no text of its own and is named througharia-labelby a requireddataprop holding the same text, so the control is never without a name: an id list that names no element leaves the name from that prop. - Fabricate moves no focus, except that focus moves among the tabs of one
EditorTabsstrip on a press and on the keys its section names, and the platform moves it among the radios of oneRadioCardGroupor oneSegmentedControlon the arrow keys, Fabricate moves it among the radios of one manualRadioCardGroupon the arrow keys, Home and End, and among the swatches of oneTintSwatcheson the keys its section names, and when anupdatedisables or removes thePaginationarrow that holds focus, Fabricate moves it to that pager’s other arrow or its checked page-size radio, as its section states, each never out oftarget. AModalwithtrapFocusis the exception to that rule: Fabricate moves focus into its dialog as it opens, keeps Tab inside it, and returns focus to the element that held it a frame after it closes, as its section states. AnIconPickeris the exception totarget: Fabricate moves focus from its trigger into its open list’s query field, outsidetarget, and back to the trigger when a choice, Escape or Tab in the query field closes the list, from which the browser moves a forward Tab on, as its section states. AnActionMenuis another exception totarget: Fabricate moves focus from its trigger into its open menu, among the menu’s items on the keys its section names, and back to the trigger when a choice, Escape or Tab closes it, as its section states. Anupdateordestroythat removes a focused control leaves focus on the document body, where Foundry’s keybindings apply, except where this bullet’s first sentence has Fabricate move it off aPaginationarrow, so move focus to an element of your own before you call either. The destination is, in order: the control the press leads to. The next control in your own content, then the previous one. And where none exists, the heading or container of the regiontargetsits in, which you givetabindex="-1". Where the destination is drawn by the same change, draw it first, focus it, and then remove the control. - To return focus to a published control, after a dialog its press opened has closed, focus the focusable element inside
targetthat the component’s section names; nothing else insidetargetis yours to select. - A press bubbles from the control as a
click, except a press on aSelect,IconPickerorActionMenutrigger, which stops at the trigger, and a press inside an openSelectorIconPickerlist orActionMenumenu, which stops there. An element of yours abovetargetthat listens forclickreceives every other press too. A press inside an openModaldialog bubbles to the dialog’s host and its ancestors, never through theModal’s owntarget. Keeptargetout of any element of your own that carriesdata-action, and pass nodata-actionthrough rest to a component that draws a control: the window dispatches the nearestdata-actionabove the press, andclosecloses it, as a DialogV2 button’s own action name submits it. Where a component’s rest lands on the control itself,data-actionis refused: the press would dispatch it,closeclosing the window and, in Foundry 14,detachmoving it to its own browser window. Keeptargetout of a<label>, an<a>and a<button>of your own. - A control is unavailable only through a prop its section names. A natively
disabledcontrol leaves the tab order and cannot take focus, so never disable the control that holds focus, except aPaginationarrow, which its section lets anupdatedisable: ignore the press instead, and where the control must then become unavailable, first move focus to the destination the “Fabricate moves no focus” bullet orders. Disabling the control that holds focus drops focus to the document body, where Foundry’s keybindings apply, as removing it does, except wherePagination’s section states that Fabricate moves it. In a document sheet the user cannot edit, Foundry disables every form control inside the sheet’s<form>on each render, a published control already mounted there among them, and the control looks as it did, apart from a switch’s pointer cursor, which becomesnot-allowed, so mount a control there from the sheet’s render hook or aftersuper._onRender, once that pass has run. - A control that shows a state (pressed, checked, selected, current) takes it from a
dataprop and exposes it in the accessibility tree as well as in colour. A press reports through the callback, and the control shows the new state when yourupdatepasses it; its section says where a native control changes itself first. The attribute that exposes the state is the component’s own, soaria-pressed,aria-checked,aria-selectedandaria-currentare refused as props.aria-expandedis anariaprop because it reports a region the control does not draw, which the component shows nowhere. ADisclosuredraws the body its button reports, so it writesaria-expandeditself, from itsopenprop, and takes noariaprop. - A control takes an ARIA attribute from you only through an
ariaprop its section names; every otheraria-*name is refused. - An
ariaprop that takes an id (aria-describedby,aria-labelledby) names an element you own, in the same tree astarget, outsidetargetor inside one of its content slots. The element it names holds text you also draw visibly; Fabricate does not check this. Fabricate resolves and checks nothing: an id that is absent, or that two elements in that tree share, names or describes nothing, and keeping it unique is yours. In a Foundry 14 detached window Foundry moves the window’s element whole to the other document, so a described element inside that element goes with it and anything you appended tobodystays behind. - In Foundry 13 and 14 the tooltip sets
aria-describedbytotooltipon the element it is shown for and removes the attribute when it closes. A tooltip on an ancestor leaves the control alone, so this reaches a published control only when you show one on it yourself, withgame.tooltip.activateor a Tour step that selects it, or onIconButton, whose own tooltip opens on its button under the pointer and keyboard focus alike, as its section states, and on aButtonorStepperbutton given a tooltip prop, as each section states. Restore the prop once the tooltip has closed, which you can see whengame.tooltip.elementis no longer your control or after callinggame.tooltip.deactivate()yourself: callupdatewithout the prop,awaitanything once thatupdatehas returned (await Promise.resolve()is enough), and callupdatewith it again. AButtonorIconButtondrawing adescriptionwrites itsaria-describedbyback itself, as each section states. Without theawaitbetween them Fabricate may draw the two as the second alone, which writes nothing, and a restore you make while the tooltip is still open is removed with it. - A control shows nothing under the pointer that it does not also show under keyboard focus. Where a component’s rest lands on the control itself,
data-cursoris refused: at the next pointer release anywhere in the document Foundry copies its value into the control’s inlinecursorand deletes the attribute. - A control’s only motion is its own state change: a fade, and on
StatusTogglethe knob’s travel along its track. ADisclosuredraws none: its chevron changes direction at once and its head statestransition: none, so Foundry core’s half-second tween on every button does not reach it. Underprefers-reduced-motion: reduceFabricate removes that motion inside a Fabricate window and under a standalone style root; elsewhere the fade is the host’s own. - A control opens no tooltip of its own at version 1, Fabricate’s or Foundry’s: no prop names one, and the HTML
titleattribute is refused as a rest key. The one exception isIconButton, which shows its name as its tooltip under the pointer and keyboard focus alike, as its section states, and so do theActionMenutrigger and theModalclose control, each of which is anIconButton. AButtongiventooltipand aStepperbutton givendecrementTooltiporincrementTooltipshow that hint the same way, under the pointer and keyboard focus alike, as each section states. The name aListRowbutton holds carries its own text as a nativetitle, and so does eachTintSwatchesswatch its name, as each section states. ASegmentedControloption’stitleis written as that segment’sdata-tooltip-text, which Foundry’s hover listener shows on the pointer alone, and as the radio’s accessible description, as its section states. Adata-tooltip-textyou pass through rest lands on the component’s root: its tooltip stays open while the pointer is over the control and opens on pointer hover only, so it says nothing the control’s name does not. Where a component’s rest lands on the control itself,data-tooltipand every name that startsdata-tooltip-are refused, so the control shows the pointer nothing it does not show keyboard focus. A tooltip attribute ontargetitself is yours, and is held to the same rule. A control whose face is a glyph alone is published only with a prop for its name that isrequired, orrequiredWhenthe prop that draws the control, and its section says whether the pointer is shown that name.
Standalone style root
Button, IconButton, StatusToggle, InspectorCard, Well, Field, SearchField, Stepper, Select, SegmentedControl, RadioCardGroup, EditorTabs, Pagination, IconPicker, ActionMenu, Modal, ToggleCard, SelectionCheckbox, Disclosure, Typeahead, Popover and TintSwatches state the root any and are drawn in your own window, dialog or sheet, where target has no Fabricate root; Stepper only in a window that holds target in no <form>, as Stepper states. The panel Select, IconPicker, ActionMenu, Modal, Typeahead or Popover opens there, with no overlayHost, is drawn on the standalone layer, as Overlays states, and that layer counts as a Fabricate root. A Fabricate root is a .fabricate ancestor of target that is not a standalone style root. Your own window carries none, so at mount Fabricate writes one <div> in target with display: contents, and draws the component inside it. That element is the standalone style root. It is judged at mount and mountMany only, as the Fabricate root is. Under a Fabricate root Fabricate writes none, so a mount inside the Manager or the player window draws exactly as before. A target in a content slot of a mount that sits under a Fabricate root, or inside a standalone style root, is under a root, so no second one is written there.
The standalone style root is private, as are its classes and its data-fabricate-theme copy. Select none of it. It carries no role, no aria-* and no tabindex, and the data-* attributes you pass as rest never land on it. It is never an overlay host. destroy and a fault remove it, so target is left as it was. If a re-render of yours already took it away with the old content, there is nothing to remove. If you call target.replaceChildren(), you supersede the mount’s claim on target, as you do for any mount.
What it gives you and what it leaves to you:
- It states the Fabricate window’s ink and its dark colour scheme, so your
ButtonandStatusToggleread as they do in a Fabricate window. The typeface still comes fromtarget, so setfont-family,font-sizeandline-heightthere. - It paints no ground, so you supply one. Paint
--fab-bg-1ontarget, or nest the component in anInspectorCardor aWell, as forCallout. On Foundry’s light theme whatever a component draws ontarget’s ground rather than on a fill of its own otherwise falls short of its contrast floor: everyButtonandIconButtonrole butprimary, theActionMenutrigger among them, the switch’s off face,Field’s ink and the caption and hint you draw in its slot,SearchField’s andStepper’s ink on their translucent shells, theformSelecttrigger’s and theIconPickertrigger’s ink on theirs,SegmentedControl’s labels atdensity'default'or in the'pill'shape,EditorTabs’ tabs and a compactPagination’s summary, page-size caption and arrows.RadioCardGroup’s cards, a defaultPaginationbar, theinlineandtoolbarSelecttriggers, and the list, menu or dialog an overlay opens paint their own ground.--fab-bg-1ontargetresolves from the document’s theme, which agrees with the standalone style root’s except in a detached window. - Your own content in a content slot of such a mount takes the Fabricate window’s ink, dark colour scheme, palette tokens, focus ring and reduced-motion rule, as it does in a Fabricate window. Fabricate’s heading normalisation does not reach it, so a heading there takes Foundry’s own face and ink.
- A component whose root is
fabricateormanager, mounted in a content slot of such a mount with no Fabricate root above, throws<name> needs a Fabricate window ancestoror<name> needs a Fabricate manager ancestor. A standalone style root is no Fabricate root. - A component drawn under a standalone style root throws
<name> cannot be drawn in a shadow rootwheretargethas no Fabricate root and its root node is a shadow root. Fabricate’s module sheet reaches a document’s head and no shadow root. A detachedtargetthat is no shadow root’s is drawn, under a standalone style root written atmount. - In a Foundry 14 detached window the module sheet is present, so a mount made there is drawn in the theme Fabricate reads from its own document element at
mount. A later theme change reaches a standalone style root in Fabricate’s own document and none in a detached window. - A normal declaration in an unlayered sheet of the host’s outranks the module sheet that draws the component, at any specificity. The exception is
transitionunder reduced motion, which the module sheet states!important. Your own module sheet, one its manifest gives nolayer, loads inlayer(modules)beside Fabricate’s, where specificity and then order decide. - A document sheet disables every control in its form when the document is not editable, so mount after
super._onRender. - A component is drawn under the standalone style root only where its admission test holds. That test mounts it in a bare ApplicationV2
.window-contentand compares every element it draws with the same props in the player window, at rest, under keyboard focus, under the pointer and under reduced motion. ForSelect,IconPicker,ActionMenu,ModalandPopoverit compares the open list, menu, dialog or panel too, on the standalone layer against the player window’s. A panel on the layer draws in a Fabricate window’s typeface and at Foundry’s application size, as a panel in the player window does, and not in the size Foundry’s<body>states. Its line height is inherited from the page body, as in a Foundry window, and its ink is Fabricate’s. The test page sets one typeface on its body so both arms compare like with like. It runs over Fabricate’s core-min fixture and, where the harvest exists, Foundry 14.365’s core sheet. The harvested arm draws under no Foundry theme class. Core’s container rules (.standard-form,.form-group,.form-fields,.form-footer,.dialog-buttons) reach such a control or text input in a dialog or form sheet wherever they select a descendant or set a custom property the component does not state, as.standard-form buttonsets--button-size, and a DialogV2’s content is always a.standard-form; the test does not measure them. Core’sfieldset,legend, radio andtextarearules are measured only where the harvest exists. An ApplicationV1 window is not a supported target, and Foundry 13 is unmeasured. Chromium draws a search field’s cancel button and a number field’s spin buttons itself, in the dark colour scheme, and computes no author style for them, so the test does not read them. A Font Awesome glyph’s box follows the Font Awesome the running build ships, which the test does not measure.
A worked mount follows: a save control in an ApplicationV2 of your own, which carries no Fabricate root.
// After `load(['Button'])` has resolved and `fabricate.ready` has fired.
#save = null;
_onRender(context, options) {
super._onRender(context, options); // A document sheet disables its controls here, so mount after it.
const fabUi = game.fabricate?.api?.ui;
// A Fabricate that predates the standalone style root describes `Button` as `fabricate`.
if (fabUi?.describe?.('Button')?.root !== 'any') return;
const target = this.element.querySelector('[data-acme-save]'); // An empty element you own, on a `--fab-bg-1` ground.
this.#save?.destroy(); // A re-render replaced the old target.
this.#save = fabUi.mount('Button', {
target,
props: { role: 'primary', children: 'Save notes', onclick: () => acmeNotes.save() },
});
}
async _preClose(options) {
this.#save?.destroy();
await super._preClose(options);
}
What stays companion-owned
Fabricate publishes a primitive when a companion cannot re-draw its meaning without drifting from the design system. It does not publish a layout, a control with a single site, or a behaviour that belongs to the companion’s own window. Each piece below is settled, so a companion does not wait on a change that is not coming.
- Tabular rows and sortable column headers are companion-owned. A table is layout, not a primitive, and
ListRowis deliberately a single bordered row. Draw the grid yourself, make each sortable header a<button>, and writearia-sorton the sorted column’s header. - A timed toast is companion-owned, its position and its timing. Draw its content with a published
Notice, whoseaccenttone fits a neutral message. - A range slider, with one site, is a native
<input type="range">in the companion, styled with the design-system tokens. - An image-slot tile with a pencil overlay, with one site, is companion-owned. Compose it from a published
ButtonandMedallion. - A medallion preview above 44px, with one site, is not published. Draw the 44px tile with the name beside it, and register the departure in your own register.
- A stepper’s sign-aware ink is not published as a
tonekey. The signed text beside theSteppercarries the meaning. - A tooltip on your own element is Foundry’s
data-tooltip-text, in place of a nativetitle. A published control that takes no rest props gets atooltipkey only where its own section states one. - The keyboard reachability of a scroll region is companion-owned and is not a core dependency.
- An accent-filled primary action is not published. Adopt the success-family
primaryButtonand register the departure; the outlinedaccentand the solidurgentroles are the forward verbs the design system publishes.
Data Persistence
Fabricate stores data in Foundry’s settings and flags:
| Location | Key | Contents |
|---|---|---|
| World setting | fabricate.craftingSystems | All crafting system configurations, including each system’s Travel & Realms participation flag |
| World setting | fabricate.travelConfig | The world realm library, its reveal mode, and its modifier visibility (including each realm’s Foundry Scene Region links) |
| World setting | fabricate.gatheringParties | Fabricate-managed gathering parties (members, travel actor, current-realm override) |
| World setting | fabricate.recipes | All recipes |
| World setting | fabricate.gatheringEnvironments | Gathering environment and task configurations |
| World setting | fabricate.gatheringConfig | Gathering library, rules, condition vocabularies, and per-system gathering configuration |
| World setting | fabricate.migrationVersion | Last completed Fabricate data migration version |
| World setting | fabricate.theme | Active product UI theme (Fabricate by default, with other presets Mythwright, Ironblood Forge, Hearth & Herb, Starglass Arcana, and the fixed Foundry-inspired Foundry Native palette) |
| World setting | fabricate.experimentalFeatures | Reveals in-development Fabricate surfaces: the unimplemented recipe Graph placeholder in the crafting manager, the GM Manager’s World > Downtime route, a companion’s downtime tabs in the player window, and the GM Manager’s Premium crafting-icons advert on the world Component catalogue and Component Rules screens. Disabled by default. |
| World setting | fabricate.premiumIconsAdDismissed | Whether a GM has dismissed the GM Manager’s Premium crafting-icons advert for this world (Boolean, default false). Written true only by the advert’s dismiss control. Nothing else writes or clears it. |
| Client setting | fabricate.lastCraftingActor | Last selected crafting actor UUID |
| Client setting | fabricate.lastGatheringActor | Last selected gathering actor ID |
| Client setting | fabricate.lastComponentSources | Last selected source actor UUIDs |
| Client setting | fabricate.lastManagedCraftingSystem | Last viewed system in GM admin |
| Client setting | fabricate.lastAlchemySystem | Last selected alchemy system (discipline) for the Alchemy Workbench tab |
| Client setting | fabricate.favouriteRecipes | Favourite recipe IDs for the current client |
| User setting | fabricate.progressiveResultOrder | Player progressive result-stage order, keyed recipe:<recipeId> / salvage:<systemId>:<componentId> to a list of result ids (Object, default {}). Registered with scope: 'user', which is per user within one world. The same player in a second world reads the default. Writing it is an asynchronous, replicated document write that can reject, not a synchronous localStorage write, so a caller must await it. |
| Client setting | fabricate.gatheringHideUnavailableEnvironments | Player “hide unavailable (locked) environments” toggle for the Gathering app Environments column (Boolean, default false, per client/device) |
| Actor flag | fabricate.craftingRuns.active | In-progress crafting runs |
| Actor flag | fabricate.craftingRuns.history | Completed crafting runs |
| Actor flag | fabricate.gatheringRuns.active | In-progress gathering runs |
| Actor flag | fabricate.gatheringRuns.history | Completed gathering runs |
| Actor flag | fabricate.learnedRecipes | Learned recipe records |
| Actor flag | fabricate.discoveredGatheringRealms | Gathering realm discovery entries for the actor, keyed by realm (the legacy fabricate.discoveredGatheringRegions flag is read as a fallback and removed on the next reveal or hide) |
| Item flag | fabricate.toolUsage | { timesUsed } for limitedUses tool tracking (falls back to legacy fabricate.catalystItemUsage when absent) |
| Item flag | fabricate.toolBroken | true when a tool’s flagBroken on-break action has fired |
| Item flag | fabricate.recipeItemUsage | { timesUsed, inert? } for recipe item tracking. inert records that the copy exhausted while its book was set to become inert rather than be destroyed, and nothing in Fabricate clears it once set |
Hooks
| Hook | When | Payload |
|---|---|---|
fabricate.ready | After module initialisation and guarded startup world-time processing complete | None |
fabricate.gathering.attemptCompleted | Once per terminal gathering attempt (success/failure, immediate/timed), after side effects commit | See Subscribing To Gathering Hooks |
fabricate.gathering.eventTriggered | Once per encounter an attempt triggers | See Subscribing To Gathering Hooks |
fabricate.manager.navProviderRegistered | A companion provider takes a GM Manager navigation surface | See Manager Hooks |
fabricate.manager.navProviderUnregistered | A companion provider releases a surface | See Manager Hooks |
fabricate.manager.surfaceMounted | The Manager route hosting an extension surface renders | See Manager Hooks |
fabricate.manager.surfaceUnmounted | That route is torn down | See Manager Hooks |
fabricate.manager.surfaceTabChanged | The active tab of a hosted surface changes | See Manager Hooks |
fabricate.player.navProviderRegistered | A companion provider claims a player-window navigation surface | See Player Hooks |
fabricate.player.navProviderUnregistered | A companion provider releases a player surface | See Player Hooks |
fabricate.player.surfaceMounted | The player window mounts an extension surface | See Player Hooks |
fabricate.player.surfaceUnmounted | That surface is torn down | See Player Hooks |
fabricate.player.surfaceTabChanged | The active tab of a mounted player surface changes | See Player Hooks |
Startup world-time processing awaits crafting, salvage, and gathering settlement before fabricate.ready fires. Later Foundry updateWorldTime events dispatch the same processors without blocking the hook. Individual processor failures are caught and logged so one subsystem does not prevent the others from running.