GrConfigProvider

The local prop of the component → componentDefaults[Component] → the global size → the component’s own default. Hence the rule for the authors of components: a prop configurable through the provider is declared with an undefined default, otherwise Vue substitutes its own value before the component looks into the config.

The componentDefaults of the top provider lie on top of two layers that need no provider: the default props of the document’s current theme (extensions.granularity.componentDefaults of its entry in the virtual:granum/themes manifest, if it was handed to granularityThemePlugin) and of the application (createGranularity({ componentDefaults })). They also apply where there is no provider in the tree at all. The theme layer follows useTheme().setTheme: after a theme change the components take its props.

A provider with theme — a theme island — replaces the document theme’s layer with the default props of its own theme or removes it if the theme has none of its own: the props of one theme on the components of another would look foreign. The application and the providers above the island stay on top.

The effective config can be read from the application with useGrConfig() — it is public.

The size of the provider is about controls (xs | sm | md | lg). Overlays have a scale of their own (sm | md | lg | xl | full), and the global size does not touch them: xs means nothing for a modal window. The size of a window is set pointwise:

<GrConfigProvider :component-defaults="{ GrModal: { size: 'lg' } }">

That is how GrModal, GrDialog, GrConfirmDialog, GrPromptDialog, GrCommandPalette and GrDrawer are configured.

The adapter is handed down always and through a facade rather than by value: an adapter created asynchronously (the usual loading of a locale) will reach the children when it appears, and swapping the adapter on a change of language redraws the strings. If the prop is not set, the facade delegates to the adapter found higher up the tree — installation through app.use() keeps working.

locale is a request to the adapter to switch: the provider calls syncLocale, and on an @feugene/fint-i18n instance, which has no such method, setLocale. The source of truth remains the adapter itself: the provider neither stores the locale nor replaces it.

mode puts the pair of the mode of the document’s current theme into data-theme on the wrapper: mode="dark" gives slate-dark. Every mode is declared on its own pair — [data-theme="slate-light"] alongside :root, and [data-theme="slate-dark"] — so an island works both ways with no extra styles: a dark one inside a light page and a light one inside a dark page. Together with the roles the island gets the color-scheme of its mode, and the derived formulas (--gr-primary-hover and its neighbours) and the references of per-component themes are recomputed on it rather than inherited already computed from the page.

theme is an island of another build theme: theme="clay" mode="dark" writes data-theme="clay-dark". The theme must be in themes of the granum config — otherwise none of the sheets has its pairs. The island loads the additional theme’s sheet itself by the address in the manifest; while it loads, the subtree shows the inherited values, and a failed load leaves them. A page that always shows the theme had better import the sheet statically — virtual:granum/themes/clay.css: then there is no frame without values, and the loader recognises such a sheet and does not download it again. The island’s mode is its mode, otherwise the document’s mode; if the theme has no such mode — the first one of the same scheme, otherwise its default mode (the same rule as setTheme), and in a dev build the provider warns that the theme lacks the given mode. A nested provider with mode alone changes the island’s mode. A mode name in theme (theme="dark") is a common mistake: a dev build warns about it too, as well as about a sheet that failed to load.

The pairs come from the theme manifest handed to granularityThemePlugin (or initThemeEarly) — together with the attribute name, if the build changed it.

The application’s own tokens that refer to roles (--app-accent: var(--gr-primary)) are best declared on the same boundary — :root, [data-theme]: a var() value is substituted where the property is declared, and one declared only on :root is inherited by the island already computed.

The panels of overlays are teleported into body, that is, in the DOM they live outside the wrapper — but in the component tree they stay inside, so inject reaches them and they set the pair for themselves. That covers the modal, the drawer, the dropdown, the popover, the tooltip, the selects, the toaster and the image viewer.

The theme and the mode of the document are the job of useTheme/initThemeEarly. The props of the provider are precisely about islands; there are no two mechanisms for the same thing in the package.

zIndexBase recomputes all seven layers of the scale from the base (bottom-nav −150, navbar −100, dropdown +0, tooltip +50, modal +100, loading +150, toast +200 — the same steps as in the theme) and sets them on <html>, restoring the previous values on unmount. The whole scale moves: a layer left in place would end up under somebody else’s modal or above its toasts.

On :root rather than on the wrapper for exactly the reason the theme is set by the panels themselves: a panel moves into body and does not see the variables of the subtree. “Layers by subtree” would be a false promise, so the scale is one per document — a second provider with a different base warns about the conflict in a dev build.

The same result is achieved with seven lines of CSS; the prop is needed where the base comes from the runtime (a micro-frontend inside someone else’s application).

portalTarget names the container the overlays of the subtree move into: modals, select panels, toasts, imperative dialogs. By default that is the shared #gr-portal in body, which the package creates itself on the first opening.

<GrConfigProvider portal-target="#my-app-portal">
  <App />
</GrConfigProvider>

It is needed where the application lives in a container of its own: a micro-frontend inside someone else’s page, a shadow DOM, CSS scoping under a particular root. The value is inherited by nested providers, and an individual component may override it with the teleportTo prop.

The provider only names the target — it does not create the DOM: the container has to exist by the time an overlay opens. There is a single requirement on it, but a strict one: no transform, filter, contain, perspective or will-change — they create a containing block for position: fixed, and floating panels will start computing their position from the container rather than from the viewport. The details — ../z-index.md.