hudini 0.18.1 → 0.19.0

package/README.md

@@ -140,6 +140,63 @@ import { Column, Row, IconButton } from 'hudini';
 
 Check the Storybook for live, interactive examples: [Hudini on Storybook](https://renatocassino.github.io/phaser-toolkit/?path=/story/hudini--index)
 
+## 🎯 Access the plugin from your scene
+
+Use the `withHudini(scene)` accessor to get a fully typed handle to the plugin. It composes with any base scene, doesn't rely on global module augmentation, and infers your theme's tokens at the call site.
+
+```ts
+import Phaser from 'phaser';
+import { withHudini } from 'hudini';
+import type { ThemeType } from './theme'; // your createTheme() result
+
+class MyScene extends Phaser.Scene {
+  create(): void {
+    const hudini = withHudini<ThemeType>(this);
+    const pw = hudini.pw; // phaser-wind API, narrowed to your theme
+
+    this.cameras.main.setBackgroundColor(pw.color.rgb('background'));
+  }
+}
+```
+
+Call `withHudini(this)` inside `create()` / `update()` (after the plugin has mounted). Don't call it in the constructor or `init()` — the plugin isn't attached yet.
+
+### Recommended: wrap it in a project-local helper
+
+Passing `<ThemeType>` on every call gets old. Define a one-line helper once in your project so scenes stay short and the theme type stays in one place:
+
+```ts
+// src/theme.ts (in your project)
+import type { Scene } from 'phaser';
+import { createTheme, withHudini, type CreateTheme } from 'hudini';
+
+export const theme = createTheme({
+  colors: { primary: 'blue-600', danger: 'red-500' },
+  // ...
+} satisfies CreateTheme<any>);
+
+export type ThemeType = typeof theme;
+
+/** Project-local accessor — no need to pass the theme type. */
+export const withHud = (scene: Scene) => withHudini<ThemeType>(scene);
+```
+
+Now every scene is a one-liner:
+
+```ts
+import Phaser from 'phaser';
+import { withHud } from './theme';
+
+class MyScene extends Phaser.Scene {
+  create(): void {
+    const hudini = withHud(this); // fully typed against your theme
+    this.cameras.main.setBackgroundColor(hudini.pw.color.rgb('background'));
+  }
+}
+```
+
+You can name the helper whatever fits your style — `withHud`, `useHud`, `getHud`, `hud`. The lib intentionally doesn't ship an alias, so you own the naming in your codebase.
+
 ## 🧩 Components
 
 ### Column

package/dist/hudini.js

@@ -1198,6 +1198,65 @@
         };
     };
 
+    /**
+     * Opacity scale mapping following Tailwind's opacity scale.
+     * Values are in the 0..1 range, ready for Phaser's `setAlpha()`.
+     */
+    const opacityMap = {
+        '0': 0,
+        '5': 0.05,
+        '10': 0.1,
+        '15': 0.15,
+        '20': 0.2,
+        '25': 0.25,
+        '30': 0.3,
+        '35': 0.35,
+        '40': 0.4,
+        '45': 0.45,
+        '50': 0.5,
+        '55': 0.55,
+        '60': 0.6,
+        '65': 0.65,
+        '70': 0.7,
+        '75': 0.75,
+        '80': 0.8,
+        '85': 0.85,
+        '90': 0.9,
+        '95': 0.95,
+        '100': 1,
+    };
+    /**
+     * Create an opacity API bound to an optional theme opacity map.
+     * @example
+     * const o = createOpacity({ faded: 0.35 });
+     * o.value('faded'); // 0.35
+     * o.value('50');    // 0.5
+     */
+    const createOpacity = (themeOpacity) => {
+        const map = {
+            ...opacityMap,
+            ...themeOpacity,
+        };
+        const get = (key) => {
+            return typeof map[key] === 'number' ? map[key] : 0;
+        };
+        return {
+            value: (key) => {
+                return get(key);
+            },
+            percent: (key) => {
+                const ONE_HUNDRED = 100;
+                return get(key) * ONE_HUNDRED;
+            },
+            css: (key) => {
+                const ONE_HUNDRED = 100;
+                return `${get(key) * ONE_HUNDRED}%`;
+            },
+        };
+    };
+    /** Convenience instance using default opacity map (no theme). */
+    const Opacity = createOpacity(undefined);
+
     /**
      * Mapping of radius keys to their pixel values
      */
@@ -1370,6 +1429,7 @@
             overlay: 'black',
         },
         spacing: { ...spacingMap },
+        opacity: { ...opacityMap },
         typography: {
             heading: {
                 fontSize: '2xl',
@@ -1446,6 +1506,7 @@
             overlay: 'black',
         },
         spacing: { ...spacingMap },
+        opacity: { ...opacityMap },
         typography: {
             heading: {
                 fontSize: '2xl',
@@ -1507,6 +1568,7 @@
         fontSizeInstance = null;
         spacingInstance = null;
         radiusInstance = null;
+        opacityInstance = null;
         fontInstance = null;
         shadowInstance = null;
         /** Current theme configuration */
@@ -1553,6 +1615,7 @@
             this.fontSizeInstance = createFontSize(this.theme.fontSizes);
             this.spacingInstance = createSpacing(this.theme.spacing);
             this.radiusInstance = createRadius(this.theme.radius);
+            this.opacityInstance = createOpacity(this.theme.opacity);
             this.fontInstance = createFont(this.theme.fonts, this.theme.fontSizes);
             this.shadowInstance = createShadow(this.theme.effects);
         }
@@ -1575,6 +1638,9 @@
         get radius() {
             return this.radiusInstance;
         }
+        get opacity() {
+            return this.opacityInstance;
+        }
         get font() {
             return this.fontInstance;
         }
@@ -1583,9 +1649,31 @@
         }
     }
 
+    /**
+     * @deprecated Use {@link withPhaserWind} instead.
+     *
+     * Forces single inheritance, which conflicts with any user-defined `BaseScene`
+     * or other libraries that ship their own scene base class. It also relies on a
+     * non-null assertion (`pw!`) that lies to TypeScript about when the plugin is
+     * available — touching `this.pw` before the plugin mounts throws at runtime.
+     *
+     * Prefer the `withPhaserWind(scene)` accessor:
+     *
+     * ```ts
+     * import { withPhaserWind } from 'phaser-wind';
+     * import type { ThemeType } from './theme';
+     *
+     * class MyScene extends Phaser.Scene {
+     *   create() {
+     *     const pw = withPhaserWind<ThemeType>(this);
+     *   }
+     * }
+     * ```
+     *
+     * Kept exported to avoid breaking existing consumers.
+     */
     class SceneWithPhaserWind extends Phaser.Scene {
         /**
-         *
          * @param config The scene key or scene specific configuration settings.
          */
         constructor(config) {
@@ -1594,6 +1682,37 @@
         pw;
     }
 
+    /**
+     * Accessor for the Phaser Wind plugin from within a Phaser scene.
+     *
+     * Preferred over {@link SceneWithPhaserWind} (inheritance) and over module
+     * augmentation of `Phaser.Scene`, because it:
+     * - Composes with any existing base scene (no forced inheritance).
+     * - Keeps the theme type explicit at the call site (no silent `any`).
+     * - Doesn't rely on non-null assertions that lie about lifecycle.
+     *
+     * Call it inside `create()` / `update()` (after the plugin has been installed).
+     *
+     * @typeParam T - The theme config type. Pass your `ThemeType` to get
+     *   type-narrowed access to your custom tokens.
+     * @param scene - The Phaser scene instance.
+     * @returns The Phaser Wind plugin instance bound to the given theme type.
+     *
+     * @example
+     * ```ts
+     * import { withPhaserWind } from 'phaser-wind';
+     * import type { ThemeType } from './theme';
+     *
+     * class MyScene extends Phaser.Scene {
+     *   create() {
+     *     const pw = withPhaserWind<ThemeType>(this);
+     *     this.cameras.main.setBackgroundColor(pw.color.rgb('background'));
+     *   }
+     * }
+     * ```
+     */
+    const withPhaserWind = (scene) => scene.plugins.get(PHASER_WIND_KEY);
+
     var getPWFromScene$1 = function (scene) {
         return scene.pw;
     };
@@ -9522,10 +9641,33 @@
         return HudiniPlugin;
     }(Phaser$1.Plugins.BasePlugin));
 
+    /**
+     * @deprecated Use {@link withHudini} instead.
+     *
+     * Forces single inheritance, which conflicts with any user-defined `BaseScene`
+     * or other libraries that ship their own scene base class. It also relies on a
+     * non-null assertion (`hudini!`) that lies to TypeScript about when the plugin
+     * is available — touching `this.hudini` before the plugin mounts throws at
+     * runtime.
+     *
+     * Prefer the `withHudini(scene)` accessor:
+     *
+     * ```ts
+     * import { withHudini } from 'hudini';
+     * import type { ThemeType } from './theme';
+     *
+     * class MyScene extends Phaser.Scene {
+     *   create() {
+     *     const hudini = withHudini<ThemeType>(this);
+     *   }
+     * }
+     * ```
+     *
+     * Kept exported to avoid breaking existing consumers.
+     */
     var SceneWithHudini = /** @class */ (function (_super) {
         __extends(SceneWithHudini, _super);
         /**
-         *
          * @param config The scene key or scene specific configuration settings.
          */
         function SceneWithHudini(config) {
@@ -9534,6 +9676,40 @@
         return SceneWithHudini;
     }(SceneWithPhaserWind));
 
+    /**
+     * Accessor for the Hudini plugin from within a Phaser scene.
+     *
+     * Preferred over {@link SceneWithHudini} (inheritance) and over module
+     * augmentation of `Phaser.Scene`, because it:
+     * - Composes with any existing base scene (no forced inheritance).
+     * - Keeps the theme type explicit at the call site (no silent `any`).
+     * - Doesn't rely on non-null assertions that lie about lifecycle.
+     *
+     * Call it inside `create()` / `update()` (after the plugin has been installed).
+     *
+     * @typeParam T - The theme config type. Pass your `ThemeType` to get
+     *   type-narrowed access to your custom tokens (through `hudini.pw`).
+     * @param scene - The Phaser scene instance.
+     * @returns The Hudini plugin instance bound to the given theme type.
+     *
+     * @example
+     * ```ts
+     * import { withHudini } from 'hudini';
+     * import type { ThemeType } from './theme';
+     *
+     * class MyScene extends Phaser.Scene {
+     *   create() {
+     *     const hudini = withHudini<ThemeType>(this);
+     *     const pw = hudini.pw;
+     *     this.cameras.main.setBackgroundColor(pw.color.rgb('background'));
+     *   }
+     * }
+     * ```
+     */
+    var withHudini = function (scene) {
+        return scene.plugins.get(HUDINI_KEY);
+    };
+
     var getHudini = function (scene) {
         return scene.hudini;
     };
@@ -9552,6 +9728,7 @@
     exports.HudiniPlugin = HudiniPlugin;
     exports.IconButton = IconButton;
     exports.LinearProgress = LinearProgress;
+    exports.Opacity = Opacity;
     exports.PHASER_WIND_KEY = PHASER_WIND_KEY;
     exports.Panel = Panel;
     exports.PhaserWindPlugin = PhaserWindPlugin;
@@ -9569,6 +9746,7 @@
     exports.createColor = createColor;
     exports.createFont = createFont;
     exports.createFontSize = createFontSize;
+    exports.createOpacity = createOpacity;
     exports.createRadius = createRadius;
     exports.createShadow = createShadow;
     exports.createSpacing = createSpacing;
@@ -9588,8 +9766,11 @@
     exports.loadFonts = loadFonts;
     exports.merge = merge;
     exports.mergeDeep = mergeDeep;
+    exports.opacityMap = opacityMap;
     exports.palette = palette;
     exports.radiusMap = radiusMap;
     exports.spacingMap = spacingMap;
+    exports.withHudini = withHudini;
+    exports.withPhaserWind = withPhaserWind;
 
 }));