@repobuddy/storybook 2.29.0 → 2.30.0

package/esm/index.d.ts

@@ -269,6 +269,73 @@ declare function withStoryCard<TRenderer extends Renderer = Renderer>({
   ...rest
 }?: WithStoryCardProps): DecoratorFunction<TRenderer>;
 //#endregion
+//#region src/parameters/create_story_sort.d.ts
+type Story$1 = {
+  id: string;
+  importPath: string;
+  name: string;
+  title: string;
+  tags?: string[] | undefined;
+};
+type StorySortFn$1 = (a: Story$1, b: Story$1) => number;
+/**
+ * A nested ordering list. Each entry is either:
+ * - A string (matches a title segment or tag name; `'*'` is the wildcard)
+ * - A tuple `[name, children]` for nested sub-ordering (order only)
+ */
+type OrderList = Array<string | [string, OrderList]>;
+interface StorySortOptions {
+  /**
+   * Ordered list of title path segments (root-level categories).
+   * Supports nesting via tuples and `'*'` wildcard.
+   *
+   * @example
+   * ```ts
+   * order: ['Overview', 'components', ['Pages', ['Home', 'Login']], '*', 'WIP']
+   * ```
+   */
+  order?: OrderList | undefined;
+  /**
+   * Ordered list of story category tags.
+   * Stories sharing the same title are sorted by their first matching tag.
+   * `'*'` marks where stories with unlisted tags sort.
+   *
+   * @example
+   * ```ts
+   * tag: ['playground', 'use-case', 'spec', 'props', '*', 'unit', 'integration']
+   * ```
+   */
+  tag?: OrderList | undefined;
+}
+/**
+ * Creates a story sort comparator for Storybook that sorts by kind (title hierarchy)
+ * and then by tag category within the same component.
+ *
+ * In Storybook 10+, `storySort` must be defined as an inline function.
+ * Assign the result to a variable and delegate from the inline function:
+ *
+ * @example
+ * ```ts
+ * import { createStorySort } from '@repobuddy/storybook'
+ *
+ * const compare = createStorySort({
+ *   order: ['Overview', 'components', 'hooks', '*', 'widgets'],
+ *   tag: ['playground', 'use-case', 'example', 'spec', 'props', '*', 'edge-case', 'unit']
+ * })
+ *
+ * export default {
+ *   parameters: {
+ *     options: {
+ *       storySort(a, b) {
+ *         return compare(a, b)
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function createStorySort(options?: StorySortOptions): StorySortFn$1;
+//#endregion
 //#region src/parameters/define_actions_param.d.ts
 interface ActionsParam {
   actions: {
@@ -710,6 +777,7 @@ type Story = {
   importPath: string;
   name: string;
   title: string;
+  tags?: string[] | undefined;
 };
 type StorySortFn = (a: Story, b: Story) => number;
 /**
@@ -969,4 +1037,4 @@ type ExtendStoryObj<TMetaOrCmpOrArgs, S extends StoryObj<TMetaOrCmpOrArgs>, E ex
   tags?: Array<E['tag'] | (string & {})> | undefined;
 };
 //#endregion
-export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, ShowSourceOptions, SourceProps, StoryCard, StoryCardAppearance, StoryCardParam, StoryCardProps, StoryCardStatus, StoryCardThemeState, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };
+export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, OrderList, ShowHtml, ShowHtmlProps, ShowSourceOptions, SourceProps, StoryCard, StoryCardAppearance, StoryCardParam, StoryCardProps, StoryCardStatus, StoryCardThemeState, StorySortOptions, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, createStorySort, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };

package/esm/index.js

@@ -371,6 +371,140 @@ function withStoryCard({ title, status, appearance, content: contentProp, classN
 	};
 }
 //#endregion
+//#region src/parameters/create_story_sort.ts
+function getPositionInOrder(name, order) {
+	const wildcardIdx = order.indexOf("*");
+	for (let i = 0; i < order.length; i++) {
+		const entry = order[i];
+		if ((Array.isArray(entry) ? entry[0] : entry) === name) return i;
+	}
+	if (wildcardIdx !== -1) return wildcardIdx;
+	return order.length;
+}
+function getChildOrder(name, order) {
+	for (const entry of order) if (Array.isArray(entry) && entry[0] === name) return entry[1];
+}
+function isWildcardPosition(name, order) {
+	for (const entry of order) if ((Array.isArray(entry) ? entry[0] : entry) === name) return false;
+	return true;
+}
+function compareByKindOrder(aTitle, bTitle, kindOrder) {
+	const aParts = aTitle.split("/");
+	const bParts = bTitle.split("/");
+	let currentOrder = kindOrder;
+	const maxDepth = Math.max(aParts.length, bParts.length);
+	for (let depth = 0; depth < maxDepth; depth++) {
+		const aPart = aParts[depth];
+		const bPart = bParts[depth];
+		if (aPart === void 0 && bPart !== void 0) return -1;
+		if (aPart !== void 0 && bPart === void 0) return 1;
+		if (aPart === bPart) {
+			const childOrder = getChildOrder(aPart, currentOrder);
+			if (childOrder) currentOrder = childOrder;
+			else continue;
+			continue;
+		}
+		const aPos = getPositionInOrder(aPart, currentOrder);
+		const bPos = getPositionInOrder(bPart, currentOrder);
+		if (aPos !== bPos) return aPos - bPos;
+		const aIsWildcard = isWildcardPosition(aPart, currentOrder);
+		const bIsWildcard = isWildcardPosition(bPart, currentOrder);
+		if (aIsWildcard && bIsWildcard) return aPart.localeCompare(bPart, void 0, { numeric: true });
+		return aPart.localeCompare(bPart, void 0, { numeric: true });
+	}
+	return 0;
+}
+function getTagPriority(tags, tagOrder) {
+	if (!tags) return getWildcardOrEnd(tagOrder);
+	let bestPriority = -1;
+	for (const tag of tags) {
+		const pos = getExplicitPosition(tag, tagOrder);
+		if (pos !== -1 && (bestPriority === -1 || pos < bestPriority)) bestPriority = pos;
+	}
+	if (bestPriority === -1) return getWildcardOrEnd(tagOrder);
+	return bestPriority;
+}
+function getExplicitPosition(name, order) {
+	for (let i = 0; i < order.length; i++) {
+		const entry = order[i];
+		if ((Array.isArray(entry) ? entry[0] : entry) === name) return i;
+	}
+	return -1;
+}
+function getWildcardOrEnd(order) {
+	const wildcardIdx = order.indexOf("*");
+	return wildcardIdx !== -1 ? wildcardIdx : order.length;
+}
+/**
+* Creates a story sort comparator for Storybook that sorts by kind (title hierarchy)
+* and then by tag category within the same component.
+*
+* In Storybook 10+, `storySort` must be defined as an inline function.
+* Assign the result to a variable and delegate from the inline function:
+*
+* @example
+* ```ts
+* import { createStorySort } from '@repobuddy/storybook'
+*
+* const compare = createStorySort({
+*   order: ['Overview', 'components', 'hooks', '*', 'widgets'],
+*   tag: ['playground', 'use-case', 'example', 'spec', 'props', '*', 'edge-case', 'unit']
+* })
+*
+* export default {
+*   parameters: {
+*     options: {
+*       storySort(a, b) {
+*         return compare(a, b)
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+function createStorySort(options = {}) {
+	return (a, b) => compareStories(a, b, options);
+}
+/**
+* Compares two stories for sorting by kind (title hierarchy)
+* and then by tag category within the same component.
+*
+* Use this directly inside an inline `storySort` function in Storybook 10+,
+* which requires `storySort` to be defined as an inline function.
+*
+* @example
+* ```ts
+* import { compareStories, type OrderList } from '@repobuddy/storybook'
+*
+* const order: OrderList = ['Overview', 'components', '*']
+* const tag: OrderList = ['playground', 'use-case', '*', 'unit']
+*
+* export default {
+*   parameters: {
+*     options: {
+*       storySort(a, b) {
+*         return compareStories(a, b, { order, tag })
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+function compareStories(a, b, options = {}) {
+	const { order: kindOrder, tag: tagOrder } = options;
+	if (kindOrder && a.title !== b.title) {
+		const kindResult = compareByKindOrder(a.title, b.title, kindOrder);
+		if (kindResult !== 0) return kindResult;
+	}
+	if (a.title !== b.title) return a.title.localeCompare(b.title, void 0, { numeric: true });
+	if (tagOrder) {
+		const aPriority = getTagPriority(a.tags, tagOrder);
+		const bPriority = getTagPriority(b.tags, tagOrder);
+		if (aPriority !== bPriority) return aPriority - bPriority;
+	}
+	return a.name.localeCompare(b.name, void 0, { numeric: true });
+}
+//#endregion
 //#region src/parameters/define_actions_param.ts
 /**
 * Defines actions parameters for Storybook stories.
@@ -589,4 +723,4 @@ function whenRunningInTest(decoratorOrHandler) {
 	};
 }
 //#endregion
-export { ShowHtml, StoryCard, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };
+export { ShowHtml, StoryCard, createStorySort, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.29.0",
+  "version": "2.30.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -27,6 +27,7 @@
     "#repobuddy/storybook": "./src/index.ts",
     "#repobuddy/storybook/manager": "./src/manager/index.ts",
     "#repobuddy/storybook/storybook-addon-tag-badges": "./src/storybook-addon-tag-badges/index.ts",
+    "#storybook-addon-tag-badges": "./src/storybook-addon-tag-badges/index.ts",
     "#repobuddy/storybook/storybook-dark-mode": "./src/storybook-dark-mode/index.ts"
   },
   "exports": {

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './components/story_card.tsx'
 export * from './decorators/show_doc_source.tsx'
 export * from './decorators/show_source.tsx'
 export * from './decorators/with_story_card.tsx'
+export * from './parameters/create_story_sort.ts'
 export * from './parameters/define_actions_param.ts'
 export * from './parameters/define_backgrounds_param.ts'
 export * from './parameters/define_docs_param.ts'

package/src/parameters/create_story_sort.ts

@@ -0,0 +1,216 @@
+type Story = {
+	id: string
+	importPath: string
+	name: string
+	title: string
+	tags?: string[] | undefined
+}
+
+type StorySortFn = (a: Story, b: Story) => number
+
+/**
+ * A nested ordering list. Each entry is either:
+ * - A string (matches a title segment or tag name; `'*'` is the wildcard)
+ * - A tuple `[name, children]` for nested sub-ordering (order only)
+ */
+export type OrderList = Array<string | [string, OrderList]>
+
+export interface StorySortOptions {
+	/**
+	 * Ordered list of title path segments (root-level categories).
+	 * Supports nesting via tuples and `'*'` wildcard.
+	 *
+	 * @example
+	 * ```ts
+	 * order: ['Overview', 'components', ['Pages', ['Home', 'Login']], '*', 'WIP']
+	 * ```
+	 */
+	order?: OrderList | undefined
+
+	/**
+	 * Ordered list of story category tags.
+	 * Stories sharing the same title are sorted by their first matching tag.
+	 * `'*'` marks where stories with unlisted tags sort.
+	 *
+	 * @example
+	 * ```ts
+	 * tag: ['playground', 'use-case', 'spec', 'props', '*', 'unit', 'integration']
+	 * ```
+	 */
+	tag?: OrderList | undefined
+}
+
+function getPositionInOrder(name: string, order: OrderList): number {
+	const wildcardIdx = order.indexOf('*')
+	for (let i = 0; i < order.length; i++) {
+		const entry = order[i]
+		const entryName = Array.isArray(entry) ? entry[0] : entry
+		if (entryName === name) return i
+	}
+	if (wildcardIdx !== -1) return wildcardIdx
+	return order.length
+}
+
+function getChildOrder(name: string, order: OrderList): OrderList | undefined {
+	for (const entry of order) {
+		if (Array.isArray(entry) && entry[0] === name) {
+			return entry[1]
+		}
+	}
+	return undefined
+}
+
+function isWildcardPosition(name: string, order: OrderList): boolean {
+	for (const entry of order) {
+		const entryName = Array.isArray(entry) ? entry[0] : entry
+		if (entryName === name) return false
+	}
+	return true
+}
+
+function compareByKindOrder(aTitle: string, bTitle: string, kindOrder: OrderList): number {
+	const aParts = aTitle.split('/')
+	const bParts = bTitle.split('/')
+	let currentOrder = kindOrder
+
+	const maxDepth = Math.max(aParts.length, bParts.length)
+	for (let depth = 0; depth < maxDepth; depth++) {
+		const aPart = aParts[depth]
+		const bPart = bParts[depth]
+
+		if (aPart === undefined && bPart !== undefined) return -1
+		if (aPart !== undefined && bPart === undefined) return 1
+		if (aPart === bPart) {
+			const childOrder = getChildOrder(aPart!, currentOrder)
+			if (childOrder) {
+				currentOrder = childOrder
+			} else {
+				continue
+			}
+			continue
+		}
+
+		const aPos = getPositionInOrder(aPart!, currentOrder)
+		const bPos = getPositionInOrder(bPart!, currentOrder)
+
+		if (aPos !== bPos) return aPos - bPos
+
+		const aIsWildcard = isWildcardPosition(aPart!, currentOrder)
+		const bIsWildcard = isWildcardPosition(bPart!, currentOrder)
+		if (aIsWildcard && bIsWildcard) {
+			return aPart!.localeCompare(bPart!, undefined, { numeric: true })
+		}
+
+		return aPart!.localeCompare(bPart!, undefined, { numeric: true })
+	}
+
+	return 0
+}
+
+function getTagPriority(tags: string[] | undefined, tagOrder: OrderList): number {
+	if (!tags) return getWildcardOrEnd(tagOrder)
+	let bestPriority = -1
+	for (const tag of tags) {
+		const pos = getExplicitPosition(tag, tagOrder)
+		if (pos !== -1 && (bestPriority === -1 || pos < bestPriority)) {
+			bestPriority = pos
+		}
+	}
+	if (bestPriority === -1) return getWildcardOrEnd(tagOrder)
+	return bestPriority
+}
+
+function getExplicitPosition(name: string, order: OrderList): number {
+	for (let i = 0; i < order.length; i++) {
+		const entry = order[i]
+		const entryName = Array.isArray(entry) ? entry[0] : entry
+		if (entryName === name) return i
+	}
+	return -1
+}
+
+function getWildcardOrEnd(order: OrderList): number {
+	const wildcardIdx = order.indexOf('*')
+	return wildcardIdx !== -1 ? wildcardIdx : order.length
+}
+
+/**
+ * Creates a story sort comparator for Storybook that sorts by kind (title hierarchy)
+ * and then by tag category within the same component.
+ *
+ * In Storybook 10+, `storySort` must be defined as an inline function.
+ * Assign the result to a variable and delegate from the inline function:
+ *
+ * @example
+ * ```ts
+ * import { createStorySort } from '@repobuddy/storybook'
+ *
+ * const compare = createStorySort({
+ *   order: ['Overview', 'components', 'hooks', '*', 'widgets'],
+ *   tag: ['playground', 'use-case', 'example', 'spec', 'props', '*', 'edge-case', 'unit']
+ * })
+ *
+ * export default {
+ *   parameters: {
+ *     options: {
+ *       storySort(a, b) {
+ *         return compare(a, b)
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function createStorySort(options: StorySortOptions = {}): StorySortFn {
+	return (a, b) => compareStories(a, b, options)
+}
+
+/**
+ * Compares two stories for sorting by kind (title hierarchy)
+ * and then by tag category within the same component.
+ *
+ * Use this directly inside an inline `storySort` function in Storybook 10+,
+ * which requires `storySort` to be defined as an inline function.
+ *
+ * @example
+ * ```ts
+ * import { compareStories, type OrderList } from '@repobuddy/storybook'
+ *
+ * const order: OrderList = ['Overview', 'components', '*']
+ * const tag: OrderList = ['playground', 'use-case', '*', 'unit']
+ *
+ * export default {
+ *   parameters: {
+ *     options: {
+ *       storySort(a, b) {
+ *         return compareStories(a, b, { order, tag })
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+function compareStories(
+	a: { title: string; name: string; tags?: string[] },
+	b: { title: string; name: string; tags?: string[] },
+	options: StorySortOptions = {}
+): number {
+	const { order: kindOrder, tag: tagOrder } = options
+
+	if (kindOrder && a.title !== b.title) {
+		const kindResult = compareByKindOrder(a.title, b.title, kindOrder)
+		if (kindResult !== 0) return kindResult
+	}
+
+	if (a.title !== b.title) {
+		return a.title.localeCompare(b.title, undefined, { numeric: true })
+	}
+
+	if (tagOrder) {
+		const aPriority = getTagPriority(a.tags, tagOrder)
+		const bPriority = getTagPriority(b.tags, tagOrder)
+		if (aPriority !== bPriority) return aPriority - bPriority
+	}
+
+	return a.name.localeCompare(b.name, undefined, { numeric: true })
+}

package/src/parameters/story_sort.ts

@@ -11,6 +11,7 @@ type Story = {
 	importPath: string
 	name: string
 	title: string
+	tags?: string[] | undefined
 }
 
 type StorySortFn = (a: Story, b: Story) => number

package/styles.css

@@ -1,4 +1,4 @@
-/*! tailwindcss v4.2.4 | MIT License | https://tailwindcss.com */
+/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */
 @layer properties;
 @layer theme {
   :root, :host {