@repobuddy/storybook 0.9.4 → 0.11.0

package/esm/index.d.ts

@@ -1,9 +1,11 @@
 export * from '@repobuddy/test';
+export * from './decorators/show_doc_source.tsx';
+export * from './decorators/when_running_in_test.tsx';
 export * from './parameters/define_actions_param.ts';
 export * from './parameters/define_backgrounds_param.ts';
 export * from './parameters/define_docs_param.ts';
 export * from './parameters/define_layout_param.ts';
 export * from './parameters/define_parameters.ts';
-export * from './parameters/define_story_sort.ts';
 export * from './parameters/define_test_param.ts';
 export * from './parameters/define_viewport_param.ts';
+export * from './parameters/story_sort.ts';

package/esm/index.js

@@ -1,9 +1,11 @@
 export * from '@repobuddy/test';
+export * from "./decorators/show_doc_source.js";
+export * from "./decorators/when_running_in_test.js";
 export * from "./parameters/define_actions_param.js";
 export * from "./parameters/define_backgrounds_param.js";
 export * from "./parameters/define_docs_param.js";
 export * from "./parameters/define_layout_param.js";
 export * from "./parameters/define_parameters.js";
-export * from "./parameters/define_story_sort.js";
 export * from "./parameters/define_test_param.js";
 export * from "./parameters/define_viewport_param.js";
+export * from "./parameters/story_sort.js";

package/esm/manager/index.d.ts

@@ -1,2 +1 @@
 export * from './brand_title.ts';
-export * from './tag_badges.ts';

package/esm/manager/index.js

@@ -1,2 +1 @@
 export * from "./brand_title.js";
-export * from "./tag_badges.js";

package/esm/parameters/define_parameters.d.ts

@@ -1,10 +1,12 @@
 import type { BackgroundsParam, GlobalApiBackgroundsParam } from './define_backgrounds_param.ts';
 import type { DocsParam } from './define_docs_param.ts';
 import type { LayoutParam } from './define_layout_param.ts';
-import type { StorySortParam } from './define_story_sort.ts';
 import type { TestParam } from './define_test_param.ts';
 import type { ViewportParam } from './define_viewport_param.ts';
-export type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsParam> & Partial<DocsParam> & Partial<LayoutParam> & Partial<StorySortParam> & Partial<TestParam> & Partial<ViewportParam>;
+import type { StorySortParam } from './story_sort.ts';
+export type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsParam> & Partial<DocsParam> & Partial<LayoutParam> & Partial<TestParam> & Partial<ViewportParam> & {
+    options?: StorySortParam & Record<string, any>;
+} & Record<string, any>;
 /**
  * Defines parameters for Storybook stories, combining built-in parameters with custom ones.
  *

package/esm/parameters/story_sort.d.ts

@@ -0,0 +1,27 @@
+type StorySortConfig = {
+    includeNames?: boolean;
+    locales?: string;
+    method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
+    order?: string[];
+    [k: string]: unknown;
+};
+type Story = {
+    id: string;
+    importPath: string;
+    name: string;
+    title: string;
+};
+type StorySortFn = (a: Story, b: Story) => number;
+/**
+ * Interface for story sorting parameters in Storybook.
+ * Used to define how stories should be sorted in the navigation sidebar.
+ */
+export interface StorySortParam {
+    /**
+     * Configuration for story sorting. Can be either:
+     * - A StorySortConfig object specifying sort method and options
+     * - A custom sorting function that takes two stories and returns their sort order
+     */
+    storySort: StorySortConfig | StorySortFn;
+}
+export {};

package/esm/parameters/story_sort.js

@@ -0,0 +1 @@
+export {};

package/esm/storybook-addon-tag-badges/index.d.ts

@@ -0,0 +1 @@
+export * from './tag_badges.ts';

package/esm/storybook-addon-tag-badges/index.js

@@ -0,0 +1 @@
+export * from "./tag_badges.js";

package/esm/storybook-addon-tag-badges/tag_badges.d.ts

@@ -0,0 +1,35 @@
+import { type TagBadgeParameters } from 'storybook-addon-tag-badges';
+type TagBadgeParameter = TagBadgeParameters[0];
+/**
+ * Configuration for story tag badges that appear in the Storybook sidebar.
+ * Each badge is associated with a specific tag and displays an emoji with a tooltip.
+ *
+ * The badges help visually identify stories with certain characteristics:
+ * - ✏️ Editor - Stories with live editor
+ * - 🆕 New - Recently added stories
+ * - 🅱️ Beta - Stories for features in beta
+ * - 🪦 Deprecated - Stories for deprecated features
+ * - ⚠️ Outdated - Stories that need updating
+ * - 🚨 Danger - Stories demonstrating dangerous patterns
+ * - 📋 Todo - Stories marked as todo/incomplete
+ * - 📝 Code Only - Stories without visual examples
+ * - 📸 Snapshot - Stories with snapshot tests
+ * - 🧪 Unit - Stories with unit tests
+ * - 🔗 Integration - Stories with integration tests
+ *
+ * Also includes the default version badge from `storybook-addon-tag-badges`.
+ */
+export declare const editorBadge: TagBadgeParameter;
+export declare const newBadge: TagBadgeParameter;
+export declare const betaBadge: TagBadgeParameter;
+export declare const propsBadge: TagBadgeParameter;
+export declare const deprecatedBadge: TagBadgeParameter;
+export declare const outdatedBadge: TagBadgeParameter;
+export declare const dangerBadge: TagBadgeParameter;
+export declare const todoBadge: TagBadgeParameter;
+export declare const codeOnlyBadge: TagBadgeParameter;
+export declare const snapshotBadge: TagBadgeParameter;
+export declare const unitBadge: TagBadgeParameter;
+export declare const integrationBadge: TagBadgeParameter;
+export declare const tagBadges: TagBadgeParameters;
+export {};

package/esm/{manager → storybook-addon-tag-badges}/tag_badges.js

@@ -50,6 +50,15 @@ export const betaBadge = {
         tooltip: 'Beta'
     }
 };
+export const propsBadge = {
+    tags: 'props',
+    badge: {
+        text: '🔧',
+        bgColor: 'transparent',
+        borderColor: 'transparent',
+        tooltip: 'Props'
+    }
+};
 export const deprecatedBadge = {
     tags: 'deprecated',
     badge: {
@@ -104,7 +113,7 @@ export const snapshotBadge = {
         tooltip: 'Snapshot Test'
     },
     display: {
-        sidebar: ['story'],
+        sidebar: false,
         toolbar: ['story']
     }
 };
@@ -115,6 +124,9 @@ export const unitBadge = {
         bgColor: 'transparent',
         borderColor: 'transparent',
         tooltip: 'Unit Test'
+    },
+    display: {
+        sidebar: false
     }
 };
 export const integrationBadge = {
@@ -124,6 +136,9 @@ export const integrationBadge = {
         bgColor: 'transparent',
         borderColor: 'transparent',
         tooltip: 'Integration Test'
+    },
+    display: {
+        sidebar: false
     }
 };
 export const tagBadges = [
@@ -135,6 +150,7 @@ export const tagBadges = [
     deprecatedBadge,
     outdatedBadge,
     dangerBadge,
+    propsBadge,
     todoBadge,
     codeOnlyBadge,
     snapshotBadge,

package/esm/storybook-dark-mode/dark_mode_docs_container.d.ts

@@ -0,0 +1,26 @@
+import { type DocsContextProps } from '@storybook/blocks';
+import { type ThemeVars } from '@storybook/theming';
+import { type PropsWithChildren } from 'react';
+/**
+ * Creates a `DocsContainer` for `storybook` that works with `storybook-dark-mode`.
+ *
+ * @see https://github.com/hipstersmoothie/storybook-dark-mode/issues/282
+ *
+ * @example
+ * ```ts
+ * // .storybook/preview.tsx
+ * const preview: Preview = {
+ *   parameters: {
+ *     docs: {
+ *       container: createDarkModeDocsContainer()
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function createDarkModeDocsContainer(customThemes?: {
+    light?: ThemeVars | undefined;
+    dark?: ThemeVars | undefined;
+} | undefined): (props: PropsWithChildren<{
+    context: DocsContextProps;
+}>) => import("react/jsx-runtime").JSX.Element;

package/esm/storybook-dark-mode/dark_mode_docs_container.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DocsContainer } from '@storybook/blocks';
+import { themes } from '@storybook/theming';
+import { useEffect, useState } from 'react';
+import { DARK_MODE_EVENT_NAME } from 'storybook-dark-mode';
+/**
+ * Creates a `DocsContainer` for `storybook` that works with `storybook-dark-mode`.
+ *
+ * @see https://github.com/hipstersmoothie/storybook-dark-mode/issues/282
+ *
+ * @example
+ * ```ts
+ * // .storybook/preview.tsx
+ * const preview: Preview = {
+ *   parameters: {
+ *     docs: {
+ *       container: createDarkModeDocsContainer()
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function createDarkModeDocsContainer(customThemes) {
+    return function DarkModeDocsContainer(props) {
+        const [isDark, setDark] = useState(true);
+        useEffect(() => {
+            props.context.channel.on(DARK_MODE_EVENT_NAME, setDark);
+            return () => props.context.channel.removeListener(DARK_MODE_EVENT_NAME, setDark);
+        }, [props.context.channel]);
+        return (_jsx(DocsContainer, { ...props, theme: isDark ? (customThemes?.dark ?? themes.dark) : (customThemes?.light ?? themes.light), children: props.children }));
+    };
+}

package/esm/storybook-dark-mode/define_dark_mode.d.ts

@@ -0,0 +1,49 @@
+import type { CSSProperties } from '@just-web/css';
+/**
+ * Configuration parameters for `storybook-dark-mode`.
+ */
+export interface DarkModeParam {
+    /** The current theme ('dark' or 'light') */
+    current?: 'dark' | 'light' | undefined;
+    /**
+     * CSS class(es) to apply in dark mode.
+     */
+    darkClass?: string | string[] | undefined;
+    /**
+     * CSS style(s) to apply in dark mode.
+     *
+     * This only works when using `withStoryRoot`.
+     */
+    darkStyle?: CSSProperties | undefined;
+    /** CSS class(es) to apply in light mode */
+    lightClass?: string | string[] | undefined;
+    /**
+     * CSS style(s) to apply in light mode.
+     *
+     * This only works when using `withStoryRoot`.
+     */
+    lightStyle?: CSSProperties | undefined;
+    /** Element to apply theme classes to ('html' or 'body') */
+    classTarget?: 'html' | 'body' | undefined;
+    /** Whether to apply theme styles to preview iframe */
+    stylePreview?: boolean | undefined;
+}
+/**
+ * Defines `storybook-dark-mode` parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/addons/@storybook/addon-themes#dark-mode
+ * @returns An object containing the dark mode parameter configuration
+ *
+ * @example
+ * ```ts
+ * // ./storybook/preview.tsx
+ *
+ * export const preview = {
+ *   parameters: {
+ *     ...defineDarkModeParam({ darkClass: 'dark' })
+ *   }
+ * }
+ */
+export declare function defineDarkModeParam(darkMode: DarkModeParam): {
+    darkMode: DarkModeParam;
+};

package/esm/storybook-dark-mode/define_dark_mode.js

@@ -0,0 +1,19 @@
+/**
+ * Defines `storybook-dark-mode` parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/addons/@storybook/addon-themes#dark-mode
+ * @returns An object containing the dark mode parameter configuration
+ *
+ * @example
+ * ```ts
+ * // ./storybook/preview.tsx
+ *
+ * export const preview = {
+ *   parameters: {
+ *     ...defineDarkModeParam({ darkClass: 'dark' })
+ *   }
+ * }
+ */
+export function defineDarkModeParam(darkMode) {
+    return { darkMode };
+}

package/esm/storybook-dark-mode/index.d.ts

@@ -0,0 +1,3 @@
+export * from './dark_mode_docs_container.tsx';
+export * from './define_dark_mode.ts';
+export * from './with_dark_mode.tsx';

package/esm/storybook-dark-mode/index.js

@@ -0,0 +1,3 @@
+export * from "./dark_mode_docs_container.js";
+export * from "./define_dark_mode.js";
+export * from "./with_dark_mode.js";

package/esm/storybook-dark-mode/with_dark_mode.d.ts

@@ -0,0 +1,22 @@
+import type { CSSProperties } from '@just-web/css';
+import type { DecoratorFunction } from 'storybook/internal/types';
+/**
+ * Applies additional dark mode behavior.
+ *
+ * @see https://storybook.js.org/addons/@storybook/addon-themes#dark-mode
+ * @returns A decorator function that applies additional dark mode behavior.
+ */
+export declare function withDarkMode(options?: {
+    /**
+     * CSS class(es) to apply to the body element.
+     *
+     * Useful when using Tailwind CSS and `classTarget: 'html'`
+     */
+    bodyClass?: string | string[] | undefined;
+    /**
+     * CSS style(s) to apply to the body element.
+     *
+     * Useful when using Tailwind CSS and `classTarget: 'html'`
+     */
+    bodyStyle?: CSSProperties | undefined;
+} | undefined): DecoratorFunction<any, any>;

package/esm/storybook-dark-mode/with_dark_mode.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { toDOMStyle } from '@just-web/css';
+import { useDarkMode } from 'storybook-dark-mode';
+/**
+ * Applies additional dark mode behavior.
+ *
+ * @see https://storybook.js.org/addons/@storybook/addon-themes#dark-mode
+ * @returns A decorator function that applies additional dark mode behavior.
+ */
+export function withDarkMode(options) {
+    return function darkModeDecorator(Story, { parameters }) {
+        const darkMode = parameters.darkMode;
+        if (!darkMode)
+            return _jsx(Story, {});
+        const dark = useDarkMode();
+        const target = darkMode.classTarget === 'html' ? document.documentElement : document.body;
+        if (dark) {
+            removeClass(target, darkMode.lightClass);
+            addClass(target, darkMode.darkClass);
+            removeStyle(target, darkMode.lightStyle);
+            addStyle(target, darkMode.darkStyle);
+        }
+        else {
+            removeClass(target, darkMode.darkClass);
+            addClass(target, darkMode.lightClass);
+            removeStyle(target, darkMode.darkStyle);
+            addStyle(target, darkMode.lightStyle);
+        }
+        if (options?.bodyClass) {
+            addClass(document.body, options.bodyClass);
+        }
+        if (options?.bodyStyle) {
+            addStyle(document.body, options.bodyStyle);
+        }
+        return _jsx(Story, {});
+    };
+}
+function addClass(target, className) {
+    if (!className)
+        return;
+    if (typeof className === 'string') {
+        target.classList.add(className);
+    }
+    else if (Array.isArray(className)) {
+        target.classList.add(...className);
+    }
+}
+function removeClass(target, className) {
+    if (!className)
+        return;
+    if (typeof className === 'string') {
+        target.classList.remove(className);
+    }
+    else if (Array.isArray(className)) {
+        target.classList.remove(...className);
+    }
+}
+function addStyle(target, style) {
+    if (style) {
+        for (const [key, value] of Object.entries(toDOMStyle(style))) {
+            target.style.setProperty(key, value);
+        }
+    }
+}
+function removeStyle(target, style) {
+    if (style) {
+        for (const key of Object.keys(toDOMStyle(style))) {
+            target.style.removeProperty(key);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "0.9.4",
+  "version": "0.11.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -23,9 +23,13 @@
       "types": "./esm/manager/index.d.ts",
       "default": "./esm/manager/index.js"
     },
-    "./react": {
-      "types": "./esm/react/index.d.ts",
-      "default": "./esm/react/index.js"
+    "./storybook-addon-tag-badges": {
+      "types": "./esm/storybook-addon-tag-badges/index.d.ts",
+      "default": "./esm/storybook-addon-tag-badges/index.js"
+    },
+    "./storybook-dark-mode": {
+      "types": "./esm/storybook-dark-mode/index.d.ts",
+      "default": "./esm/storybook-dark-mode/index.js"
     },
     "./testing": {
       "types": "./esm/testing.d.ts",
@@ -38,6 +42,7 @@
     "!**/*.{spec,test,unit,accept,integrate,system,perf,stress,study,stories}.*"
   ],
   "dependencies": {
+    "@just-web/css": "^0.4.0",
     "@repobuddy/test": "^1.0.0"
   },
   "devDependencies": {
@@ -66,6 +71,26 @@
     "vite": "^6.3.4",
     "vitest": "^3.1.2"
   },
+  "peerDependencies": {
+    "@storybook/blocks": ">= 8.6.12",
+    "@storybook/theming": ">= 8.6.12",
+    "storybook-addon-tag-badges": ">= 1.4.0",
+    "storybook-dark-mode": ">= 4.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@storybook/blocks": {
+      "optional": true
+    },
+    "@storybook/theming": {
+      "optional": true
+    },
+    "storybook-addon-tag-badges": {
+      "optional": true
+    },
+    "storybook-dark-mode": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rimraf .turbo coverage esm storybook-static *.tsbuildinfo",

package/readme.md

@@ -23,7 +23,7 @@ For example:
 import { defineLayoutParam } from '@repobuddy/storybook'
 
 export const MyStory: StoryObj = {
-  parameters: defineLayoutParam('fullscreen')
+	parameters: defineLayoutParam('fullscreen')
 }
 ```
 
@@ -34,13 +34,13 @@ and also allow you to specify additional parameter types.
 import { defineParameters, type ActionsParam } from '@repobuddy/storybook'
 
 export const MyStory: StoryObj = {
-  parameters: defineParameters<ActionsParam>({
-    layout: 'fullscreen',
-    // this is typed
-    actions: {
-      disable: true
-    }
-  })
+	parameters: defineParameters<ActionsParam>({
+		layout: 'fullscreen',
+		// this is typed
+		actions: {
+			disable: true
+		}
+	})
 }
 ```
 
@@ -59,7 +59,7 @@ addons.setConfig({
 })
 ```
 
-### Tag Badges
+### `storybook-addon-tag-badges`
 
 If you use [`storybook-addon-tag-badges`][`storybook-addon-tag-badges`],
 we provide a different set of badges that uses emojis:
@@ -80,11 +80,50 @@ we provide a different set of badges that uses emojis:
 To use them, add them to your `.storybook/manager.ts`:
 
 ```ts
-import { tagBadges } from '@repobuddy/storybook/manager'
+import { tagBadges } from '@repobuddy/storybook/storybook-addon-tag-badges'
 import { addons } from '@storybook/manager-api'
 
 addons.setConfig({ tagBadges })
 ```
 
+You can also import only the one you need:
+
+```ts
+import { newBadge } from '@repobuddy/storybook/storybook-addon-tag-badges'
+import { defaultConfig } from 'storybook-addon-tag-badges'
+
+addons.setConfig({ tagBadges: [newBadge, ...defaultConfig] })
+```
+
+### `storybook-dark-mode`
+
+[`@repobuddy/storybook`][`@repobuddy/storybook`] provides a few utilities to work with [`storybook-dark-mode`][`storybook-dark-mode`].
+
+```ts
+// .storybook/preview.tsx
+import {
+	createDarkModeDocsContainer,
+	defineDarkModeParam,
+	withDarkMode
+} from '@repobuddy/storybook/storybook-dark-mode'
+
+export const preview: Preview = {
+	parameters: {
+		docs: {
+		container: createDarkModeDocsContainer()
+		},
+		darkMode: defineDarkModeParam({
+			classTarget: 'html',
+			darkClass: 'dark',
+			stylePreview: true
+		})
+	},
+	decorators: [withDarkMode({
+		bodyClass: 'dark:bg-black dark:text-white'
+	})]
+}
+```
+
 [`@repobuddy/storybook`]: https://github.com/repobuddy/storybook
 [`storybook-addon-tag-badges`]: https://github.com/Sidnioulz/storybook-addon-tag-badges
+[`storybook-dark-mode`]: https://github.com/hipstersmoothie/storybook-dark-mode

package/src/index.ts

@@ -1,9 +1,11 @@
 export * from '@repobuddy/test'
+export * from './decorators/show_doc_source.tsx'
+export * from './decorators/when_running_in_test.tsx'
 export * from './parameters/define_actions_param.ts'
 export * from './parameters/define_backgrounds_param.ts'
 export * from './parameters/define_docs_param.ts'
 export * from './parameters/define_layout_param.ts'
 export * from './parameters/define_parameters.ts'
-export * from './parameters/define_story_sort.ts'
 export * from './parameters/define_test_param.ts'
 export * from './parameters/define_viewport_param.ts'
+export * from './parameters/story_sort.ts'

package/src/manager/index.ts

@@ -1,2 +1 @@
 export * from './brand_title.ts'
-export * from './tag_badges.ts'

package/src/parameters/define_parameters.ts

@@ -1,16 +1,15 @@
 import type { BackgroundsParam, GlobalApiBackgroundsParam } from './define_backgrounds_param.ts'
 import type { DocsParam } from './define_docs_param.ts'
 import type { LayoutParam } from './define_layout_param.ts'
-import type { StorySortParam } from './define_story_sort.ts'
 import type { TestParam } from './define_test_param.ts'
 import type { ViewportParam } from './define_viewport_param.ts'
+import type { StorySortParam } from './story_sort.ts'
 
 export type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsParam> &
 	Partial<DocsParam> &
 	Partial<LayoutParam> &
-	Partial<StorySortParam> &
 	Partial<TestParam> &
-	Partial<ViewportParam>
+	Partial<ViewportParam> & { options?: StorySortParam & Record<string, any> } & Record<string, any>
 
 /**
  * Defines parameters for Storybook stories, combining built-in parameters with custom ones.

package/src/parameters/story_sort.ts

@@ -0,0 +1,29 @@
+type StorySortConfig = {
+	includeNames?: boolean
+	locales?: string
+	method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom'
+	order?: string[]
+	[k: string]: unknown
+}
+
+type Story = {
+	id: string
+	importPath: string
+	name: string
+	title: string
+}
+
+type StorySortFn = (a: Story, b: Story) => number
+
+/**
+ * Interface for story sorting parameters in Storybook.
+ * Used to define how stories should be sorted in the navigation sidebar.
+ */
+export interface StorySortParam {
+	/**
+	 * Configuration for story sorting. Can be either:
+	 * - A StorySortConfig object specifying sort method and options
+	 * - A custom sorting function that takes two stories and returns their sort order
+	 */
+	storySort: StorySortConfig | StorySortFn
+}

package/src/storybook-addon-tag-badges/index.ts

@@ -0,0 +1 @@
+export * from './tag_badges.ts'