@nubisco/ui 2.6.0 → 2.8.0

package/dist/composables/useTheme.composable.d.ts

@@ -0,0 +1,76 @@
+import { type ComputedRef, type Ref } from 'vue';
+/**
+ * The three states a theme preference can be in.
+ *
+ * `system` is a preference in its own right, not the absence of one: it means
+ * "keep following the OS", and it stays selected while the resolved theme
+ * changes underneath it.
+ */
+export type TTheme = 'light' | 'dark' | 'system';
+/** The two themes that can actually be painted. */
+export type TResolvedTheme = 'light' | 'dark';
+export interface IThemeOptions {
+    /**
+     * localStorage key the preference is persisted under. Namespace it per
+     * application (`'analytics.theme'`), so two Nubisco products served from the
+     * same origin do not fight over one value.
+     */
+    storageKey?: string;
+    /** Preference to use when nothing is stored yet. */
+    defaultTheme?: TTheme;
+    /**
+     * Class placed on `<html>` for the dark theme. Matches the selector the
+     * library's own dark ramp is emitted under; override only if an application
+     * has its own dark stylesheet keyed on something else.
+     */
+    darkClass?: string;
+}
+export interface IThemeController {
+    /** The stored preference, including `system`. */
+    theme: Readonly<Ref<TTheme>>;
+    /** The theme actually showing right now. Never `system`. */
+    resolved: Readonly<Ref<TResolvedTheme>>;
+    /** True while the preference is `system`, for a control that marks it. */
+    followsSystem: ComputedRef<boolean>;
+    /** Pin a preference, or hand control back to the OS with `'system'`. */
+    setTheme: (value: TTheme) => void;
+    /**
+     * Flip to the opposite of what is currently showing. Always lands on an
+     * explicit `light` or `dark`, which is what a single-button toggle in a
+     * topbar wants; a three-state control should call `setTheme` instead.
+     */
+    toggle: () => void;
+}
+/**
+ * Names the storage key (and any other option) before the first `useTheme()`.
+ *
+ * Call it once, at application start, next to the other boot-time wiring:
+ *
+ * ```ts
+ * configureTheme({ storageKey: 'analytics.theme' })
+ * ```
+ *
+ * Calling it later re-reads storage and repaints, which is what an application
+ * that switches identity mid-session (or a test) wants, but it is not a
+ * per-component knob: the preference is one global piece of state, exactly like
+ * the document it paints.
+ */
+export declare function configureTheme(next?: IThemeOptions): void;
+/**
+ * Light/dark theming, with `system` as a first-class third state.
+ *
+ * The library ships both ramps and switches between them on a single class, so
+ * all this owns is the decision about when that class is present, where the
+ * preference is stored, and what happens when the OS setting changes while the
+ * application is open.
+ *
+ * ```vue
+ * const { theme, resolved, setTheme, toggle } = useTheme()
+ * ```
+ *
+ * `theme` is what the person chose (`'system'` included) and is what a settings
+ * control should bind to. `resolved` is what is actually painted, and is what
+ * an icon should follow.
+ */
+export declare function useTheme(): IThemeController;
+//# sourceMappingURL=useTheme.composable.d.ts.map

package/dist/composables/useTheme.composable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTheme.composable.d.ts","sourceRoot":"","sources":["../../src/composables/useTheme.composable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,WAAW,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAA;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEhD,mDAAmD;AACnD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5B,4DAA4D;IAC5D,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAA;IACvC,0EAA0E;IAC1E,aAAa,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IACnC,wEAAwE;IACxE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC;;;;OAIG;IACH,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB;AA4GD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,aAAkB,GAAG,IAAI,CAG7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,IAAI,gBAAgB,CAc3C"}

package/dist/global.d.ts

@@ -2,6 +2,7 @@
 // Re-run the build to update this file when components change
 import AiLabel from './components/AiLabel.vue'
 import Badge from './components/Badge.vue'
+import Banner from './components/Banner.vue'
 import BarChart from './components/Charts/BarChart.vue'
 import Blueprint from './components/Blueprint.vue'
 import BlueprintBackground from './components/BlueprintBackground.vue'
@@ -76,6 +77,7 @@ declare module 'vue' {
   interface GlobalComponents {
     NbAiLabel: typeof AiLabel
     NbBadge: typeof Badge
+    NbBanner: typeof Banner
     NbBarChart: typeof BarChart
     NbBlueprint: typeof Blueprint
     NbBlueprintBackground: typeof BlueprintBackground