@nxgt/material 3.7.5 → 3.8.0

package/dist/lib/components/ui/layout/app-shell/activity-chrome.d.ts

@@ -0,0 +1,17 @@
+/** Under a `backdrop`: the chrome's fill, from a token (activity-backdrop.css). */
+export declare const CHROME_FILL = "bg-(--nxgt-backdrop-fill-chrome)";
+/** The app bar: that fill, frosted (the blur is 0 when the user asks for less
+ * transparency). */
+export declare const CHROME_FROSTED = "bg-(--nxgt-backdrop-fill-chrome) backdrop-blur-(--nxgt-backdrop-blur)";
+/** The sidebar: a little more opaque than the app bar, for its text's contrast. */
+export declare const NAV_FROSTED = "bg-(--nxgt-backdrop-fill-nav) backdrop-blur-(--nxgt-backdrop-blur)";
+/**
+ * The top gutter, above the sticky app bar, stays in the viewport and hides
+ * what the page scrolls under it: the app bar's own fill, so nothing shows in
+ * the 8px strip. Not needed when the content region scrolls inside the frame.
+ * Without a `backdrop` it fades in over the first pixels of scroll
+ * (activity-backdrop.css), so the page at scroll top is as it always was.
+ */
+export declare function ActivityGutterMask({ hasBackdrop }: {
+    hasBackdrop: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-layout.d.ts

@@ -79,11 +79,13 @@ export type ActivityLayoutProps = {
      */
     routeTransition?: RouteTransition;
     /**
-     * A decorative background drawn behind the frame, in place of the built-in
-     * gradient and its three blobs: typically a `Background` preset from
+     * An exception to the theme's background, which the layout draws by
+     * default: under Lavande, or under no theme, the built-in gradient and its
+     * three blobs; under another theme, that theme's `background`. A node
+     * replaces it for this screen: typically a `Background` preset from
      * `@nxgt/material/backgrounds`. It fills the whole layout, sits under the
      * sidebar, the header and the content, and is `inert`, `aria-hidden` and
-     * never takes a pointer. Leave it out and the gradient is drawn as before.
+     * never takes a pointer. `false` draws no background at all, a plain page.
      * The preset's stylesheet (`@nxgt/material/backgrounds.css`) is the app's to
      * import. See the app shell guide, "Use a background preset behind the shell".
      *
@@ -99,7 +101,7 @@ export type ActivityLayoutProps = {
      * </ActivityLayout>
      * ```
      */
-    backdrop?: ReactNode;
+    backdrop?: ReactNode | false;
 } & ComponentProps<'div'>;
 /**
  * The application chrome: sidebar, header, breadcrumbs, and the routed content.

package/dist/lib/components/ui/layout/app-shell/backdrop-layer.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+/**
+ * The layer behind the content column that holds the backdrop: the theme's
+ * background (`themed`) or the app's own node. It is `inert`, `aria-hidden`
+ * and takes no pointer, so what it draws is decoration only. A `Background`
+ * node keeps its shapes whole, as the theme's does (use-keep-shapes-inside.ts).
+ */
+export declare function BackdropLayer({ backdrop, themed, }: {
+    backdrop: ReactNode;
+    themed: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/keep-shapes-inside.d.ts

@@ -0,0 +1,17 @@
+/** A box in the page's coordinates: what `getBoundingClientRect()` gives. */
+export interface Box {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** The space a shape keeps from the layer's edges and from the header band, in pixels. */
+export declare const SHAPE_MARGIN = 8;
+/**
+ * Whether a shape of the backdrop must not be drawn: it crosses an edge of the
+ * layer (or comes within `margin` of it), or it reaches the header band. The
+ * band is a list of horizontal strips (the app bar, the breadcrumb, the
+ * header card, an `EntityHeader`), full width: only their top and bottom count.
+ * A shape is kept or dropped whole, never cut.
+ */
+export declare function shapeOutside(shape: Box, layer: Box, bands: readonly Box[], margin?: number): boolean;

package/dist/lib/components/ui/layout/app-shell/theme-backdrop.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The nearest theme's background, filling the backdrop layer (it reads the
+ * theme itself). Its shapes stay whole: none crosses the layer's edge or
+ * reaches the header band (use-keep-shapes-inside.ts).
+ */
+export declare function ThemeBackdrop(): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/use-activity-backdrop.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+/**
+ * What ActivityLayout draws behind its frame. The theme's background is the
+ * default and `backdrop` the exception: `themeBackdrop` is a theme background
+ * other than Lavande's (which the built-in gradient is), `plain` is no
+ * background at all (`backdrop={false}`, or a theme without one), and
+ * `hasBackdrop` says the backdrop layer and the opaque chrome are in use.
+ * `attributes` are the root's `data-backdrop` / `data-plain`
+ * (activity-backdrop.css hides the built-in blobs and tint for either).
+ */
+export declare function useActivityBackdrop(backdrop: ReactNode | false | undefined): {
+    themeBackdrop: boolean;
+    hasBackdrop: boolean;
+    attributes: {
+        'data-backdrop': string | undefined;
+        'data-plain': string | undefined;
+    };
+};

package/dist/lib/components/ui/layout/app-shell/use-keep-shapes-inside.d.ts

@@ -0,0 +1,9 @@
+/** A callback ref for the theme's `Background`, a child of the backdrop layer (it is loaded lazily, so it mounts after this hook). */
+export declare function useKeepShapesInside(): (el: HTMLElement | null) => void;
+/**
+ * The same for a `Background` the app passes as `backdrop`: a callback ref on
+ * the backdrop layer, which finds every preset (`[data-background]`) inside it
+ * whenever the layer's content changes, so a lazily loaded or swapped preset
+ * is kept whole too. Anything else in the layer (a custom node) is left alone.
+ */
+export declare function useKeepNodeShapesInside(): (layer: HTMLElement | null) => void;

package/dist/lib/hooks/resolve-theme.d.ts

@@ -1,7 +1,52 @@
 export type ThemePreference = 'light' | 'dark' | 'system';
 export type ResolvedTheme = 'light' | 'dark';
-export declare function resolveTheme(stored: string | undefined | null, prefersDark: boolean): {
+/**
+ * The mode shown: the stored preference, else `defaultMode` (what a first
+ * visit suggests: a theme's `colorScheme`, default `system`). `system`
+ * follows `prefers-color-scheme`.
+ */
+export declare function resolveTheme(stored: string | undefined | null, prefersDark: boolean, defaultMode?: ThemePreference): {
     theme: ResolvedTheme;
     preference: ThemePreference;
 };
 export declare function applyResolvedTheme(theme: ResolvedTheme): void;
+/**
+ * The theme names an app can use. Augment it, as `AppTones` is, with the
+ * app's own themes:
+ *
+ * ```ts
+ * declare module '@nxgt/material' {
+ *   interface NxgtThemes { brand: true }
+ * }
+ * ```
+ */
+export interface NxgtThemes {
+    lavande: true;
+    ocean: true;
+    foret: true;
+    ambre: true;
+    ardoise: true;
+    corail: true;
+    menthe: true;
+    prune: true;
+    sable: true;
+    slate: true;
+    pink: true;
+    bleumono: true;
+    bluemoon: true;
+    teal: true;
+}
+export type ThemeName = Extract<keyof NxgtThemes, string>;
+/** The default theme: Lavande, which sets no `data-nxgt-theme`. */
+export declare const DEFAULT_THEME: "lavande";
+/**
+ * A stored name when it is a known theme (any well-formed name when `known` is
+ * left out), else `fallback`. A name that is no longer known resolves to the
+ * default.
+ */
+export declare function resolveThemeName(stored: string | null | undefined, known: readonly string[] | undefined, fallback: string): string;
+/**
+ * Puts the name on `<html data-nxgt-theme>`; the default, Lavande, takes the
+ * attribute off, as the boot script never sets it. No-op without `document`.
+ */
+export declare function applyThemeName(name: string): void;

package/dist/lib/hooks/theme-store.d.ts

@@ -1,9 +1,40 @@
 import { ThemePreference } from './resolve-theme.js';
-declare function readStored(): string | undefined;
+/** The theme name's key: the same as core's `THEME_STORAGE_KEY` (a spec holds them together). */
+export declare const THEME_NAME_KEY = "nxgt-theme";
 export declare const themeStore: {
-    subscribe(listener: () => void): () => void;
-    getSnapshot: typeof readStored;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => string | undefined;
     getServerSnapshot: () => string | undefined;
-    set(next: ThemePreference): void;
+    /**
+     * `system` clears the key, unless a first visit would not be `system`
+     * (`defaultMode`: a theme's `colorScheme`): then it is stored, or clearing
+     * it would bring the suggestion back.
+     */
+    set(next: ThemePreference, defaultMode?: ThemePreference): void;
+};
+/**
+ * The mounted `NxgtThemeProvider`, when there is one: it owns
+ * `<html data-nxgt-theme>`, so the store only stores. Its themes say which
+ * names are acceptable, and its default is what a cleared key means.
+ */
+interface Owner {
+    known: readonly string[];
+    fallback: string;
+}
+export declare const themeNameStore: {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => string | undefined;
+    getServerSnapshot: () => string | undefined;
+    /**
+     * Called by the provider while it is mounted; the returned function gives
+     * the attribute back to the store.
+     */
+    claim(next: Owner): () => void;
+    /**
+     * Stores the name (JSON, like `theme`). Without a provider it also applies
+     * it to `<html>`; under one, a name the provider does not know is ignored
+     * (with a warning in development) and the provider writes the attribute.
+     */
+    set(next: string): void;
 };
 export {};

package/dist/lib/hooks/use-theme.d.ts

@@ -1,12 +1,28 @@
-import { ThemePreference } from './resolve-theme.js';
+import { ThemeName, ThemePreference } from './resolve-theme.js';
+export interface UseThemeOptions {
+    /**
+     * The mode when none is stored. Default: the one `NxgtThemeProvider`
+     * gives (its `defaultMode`, else the active theme's `colorScheme`), else
+     * `'system'`.
+     */
+    defaultMode?: ThemePreference;
+}
 /**
  * The resolved theme and the stored preference. Every caller reads the same
  * store, so a toggle anywhere re-renders every reader (CodeBlock, CodeEditor…).
- * On the server, and while hydrating, the preference is `'system'`.
+ * On the server, and while hydrating, the preference is the first-visit one
+ * (`'system'` unless a provider or `defaultMode` says otherwise) and the theme
+ * name is the default (`'lavande'`, or the provider's). The name is stored
+ * apart from the mode, under `nxgt-theme`; under a `NxgtThemeProvider` or a
+ * `NxgtTheme` zone, `themeName` is the nearest one's. With no provider, the
+ * stored preset's `colorScheme` is still the first-visit mode (`bluemoon`:
+ * dark); an app's own theme needs the provider, or `defaultMode`.
  */
-export declare function useTheme(): {
+export declare function useTheme(options?: UseThemeOptions): {
     theme: import('./resolve-theme.js').ResolvedTheme;
     preference: ThemePreference;
     updateTheme: (next: ThemePreference) => void;
+    themeName: ThemeName;
+    setThemeName: (next: ThemeName) => void;
 };
-export type { ResolvedTheme, ThemePreference } from './resolve-theme.js';
+export type { ResolvedTheme, ThemeName, ThemePreference, } from './resolve-theme.js';

package/dist/lib/i18n/resources/en/en.d.ts

@@ -1178,6 +1178,10 @@ export declare const en: {
         "rating-field": {
             star: string;
         };
+        "theme-picker": {
+            label: string;
+            mode: string;
+        };
         "theme-toggle": {
             light: string;
             dark: string;

package/dist/lib/i18n/resources/en/material.json.d.ts

@@ -1168,6 +1168,10 @@ declare const _default: {
 	"rating-field": {
 		"star": "{value} of {max}"
 	},
+	"theme-picker": {
+		"label": "Theme",
+		"mode": "Mode"
+	},
 	"theme-toggle": {
 		"light": "Light",
 		"dark": "Dark",

package/dist/lib/i18n/resources/fr/fr.d.ts

@@ -1178,6 +1178,10 @@ export declare const fr: {
         "rating-field": {
             star: string;
         };
+        "theme-picker": {
+            label: string;
+            mode: string;
+        };
         "theme-toggle": {
             light: string;
             dark: string;

package/dist/lib/i18n/resources/fr/material.json.d.ts

@@ -1168,6 +1168,10 @@ declare const _default: {
 	"rating-field": {
 		"star": "{value} sur {max}"
 	},
+	"theme-picker": {
+		"label": "Thème",
+		"mode": "Mode"
+	},
 	"theme-toggle": {
 		"light": "Clair",
 		"dark": "Sombre",

package/dist/lib/i18n/resources/resources.d.ts

@@ -1176,6 +1176,10 @@ export declare const resources: {
             "rating-field": {
                 star: string;
             };
+            "theme-picker": {
+                label: string;
+                mode: string;
+            };
             "theme-toggle": {
                 light: string;
                 dark: string;
@@ -3838,6 +3842,10 @@ export declare const resources: {
             "rating-field": {
                 star: string;
             };
+            "theme-picker": {
+                label: string;
+                mode: string;
+            };
             "theme-toggle": {
                 light: string;
                 dark: string;