@rpg-engine/long-bow 0.8.66 → 0.8.68

package/src/components/Store/hooks/useStoreCart.ts

@@ -1,23 +1,30 @@
 import {
-  ICartItem,
-  IItemPack,
+  ICartItem as IBaseCartItem,
   IPurchase,
   IPurchaseUnit,
   IStoreItem,
-  PurchaseType,
+  MetadataType,
+  PurchaseType
 } from '@rpg-engine/shared';
 import { useEffect, useRef, useState } from 'react';
+import { useStoreMetadata } from './useStoreMetadata';
+
+// Extend the base cart item to include metadata
+interface ICartItem extends IBaseCartItem {
+  metadata?: Record<string, any>;
+}
 
 interface IUseStoreCart {
   cartItems: ICartItem[];
   isCartOpen: boolean;
-  handleAddToCart: (item: IStoreItem, quantity: number) => void;
+  handleAddToCart: (item: IStoreItem, quantity: number, metadata?: Record<string, any>) => void;
   handleRemoveFromCart: (itemKey: string) => void;
   handlePurchase: (onPurchase: (purchase: IPurchase) => void) => void;
   openCart: () => void;
   closeCart: () => void;
   getTotalItems: () => number;
   getTotalPrice: () => number;
+  isCollectingMetadata: boolean;
 }
 
 export const useStoreCart = (): IUseStoreCart => {
@@ -31,25 +38,62 @@ export const useStoreCart = (): IUseStoreCart => {
     };
   }, []);
 
-  const handleAddToCart = (item: IStoreItem, quantity: number) => {
-    setCartItems(prevItems => {
-      const existingItem = prevItems.find(
-        cartItem => cartItem.item.key === item.key
-      );
-
-      if (existingItem) {
-        return prevItems.map(cartItem =>
-          cartItem.item.key === item.key
-            ? {
-                ...cartItem,
-                quantity: Math.min(cartItem.quantity + quantity, 99),
-              }
-            : cartItem
+  const { collectMetadata, isCollectingMetadata } = useStoreMetadata();
+
+  const handleAddToCart = async (item: IStoreItem, quantity: number, preselectedMetadata?: Record<string, any>) => {
+    // If metadata is already provided (from inline selection), use it directly
+    if (preselectedMetadata) {
+      setCartItems(prevItems => {
+        return [
+          ...prevItems,
+          {
+            item,
+            quantity,
+            metadata: preselectedMetadata,
+          },
+        ];
+      });
+      return;
+    }
+    
+    // If item requires metadata but none was provided, collect it before adding to cart
+    if (item.metadataType && item.metadataType !== MetadataType.None) {
+      const metadata = await collectMetadata(item);
+      if (!metadata) return; // User cancelled
+
+      // Add item with metadata
+      setCartItems(prevItems => {
+        // Create new cart item with metadata
+        return [
+          ...prevItems,
+          {
+            item,
+            quantity,
+            metadata,
+          },
+        ];
+      });
+    } else {
+      // Existing add to cart logic for items without metadata
+      setCartItems(prevItems => {
+        const existingItem = prevItems.find(
+          cartItem => cartItem.item.key === item.key
         );
-      }
 
-      return [...prevItems, { item, quantity }];
-    });
+        if (existingItem) {
+          return prevItems.map(cartItem =>
+            cartItem.item.key === item.key
+              ? {
+                  ...cartItem,
+                  quantity: Math.min(cartItem.quantity + quantity, 99),
+                }
+              : cartItem
+          );
+        }
+
+        return [...prevItems, { item, quantity }];
+      });
+    }
   };
 
   const handleRemoveFromCart = (itemKey: string) => {
@@ -59,28 +103,13 @@ export const useStoreCart = (): IUseStoreCart => {
   };
 
   const handlePurchase = (onPurchase: (purchase: IPurchase) => void) => {
-    const purchaseUnits: IPurchaseUnit[] = cartItems.map(cartItem => {
-      const isPack =
-        'priceUSD' in cartItem.item &&
-        typeof cartItem.item.priceUSD === 'number';
-
-      if (isPack) {
-        const packItem = cartItem.item as IStoreItem & IItemPack;
-        return {
-          purchaseKey: packItem.key,
-          qty: cartItem.quantity,
-          type: PurchaseType.Pack,
-          name: packItem.title,
-        };
-      }
-
-      return {
-        purchaseKey: cartItem.item.key,
-        qty: cartItem.quantity,
-        type: PurchaseType.Item,
-        name: cartItem.item.name,
-      };
-    });
+    const purchaseUnits: IPurchaseUnit[] = cartItems.map(cartItem => ({
+      purchaseKey: cartItem.item.key,
+      qty: cartItem.quantity,
+      type: getPurchaseType(cartItem.item),
+      name: cartItem.item.name,
+      metadata: cartItem.metadata || cartItem.item.metadataConfig, // Use collected metadata if available
+    }));
 
     const purchase: IPurchase = {
       _id: uuidv4(),
@@ -122,9 +151,25 @@ export const useStoreCart = (): IUseStoreCart => {
     closeCart,
     getTotalItems,
     getTotalPrice,
+    isCollectingMetadata,
   };
 };
+
+// Helper functions
+function getPurchaseType(item: IStoreItem): PurchaseType {
+  // Check if the item comes from a pack based on naming convention or other property
+  if (item.key.startsWith('pack_')) {
+    return PurchaseType.Pack;
+  } else {
+    return PurchaseType.Item;
+  }
+}
+
 function uuidv4(): string {
-  throw new Error('Function not implemented.');
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+    const r = (Math.random() * 16) | 0,
+      v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
 }
 

package/src/components/Store/hooks/useStoreMetadata.ts

@@ -0,0 +1,55 @@
+import { IStoreItem, MetadataType } from "@rpg-engine/shared";
+import { useState } from "react";
+
+interface IUseStoreMetadata {
+    collectMetadata: (item: IStoreItem) => Promise<Record<string, any> | null>;
+    isCollectingMetadata: boolean;
+}
+
+export const useStoreMetadata = (): IUseStoreMetadata => {
+    const [isCollectingMetadata, setIsCollectingMetadata] = useState(false);
+    
+    const collectMetadata = async (item: IStoreItem): Promise<Record<string, any> | null> => {
+        if (!item.metadataType || item.metadataType === MetadataType.None) {
+            return null;
+        }
+
+        setIsCollectingMetadata(true);
+        
+        try {
+            // This is a promise-based approach that will be resolved when the MetadataCollector
+            // component calls the onCollect or onCancel callbacks
+            return await new Promise<Record<string, any> | null>((resolve) => {
+                // We'll store the resolver functions in a global context
+                // that will be accessible to the MetadataCollector component
+                window.__metadataResolvers = {
+                    resolve: (metadata: Record<string, any> | null) => {
+                        resolve(metadata);
+                    },
+                    item,
+                };
+            });
+        } finally {
+            setIsCollectingMetadata(false);
+            // Clean up the resolvers
+            if (window.__metadataResolvers) {
+                delete window.__metadataResolvers;
+            }
+        }
+    };
+
+    return {
+        collectMetadata,
+        isCollectingMetadata,
+    };
+};
+
+// Add TypeScript declaration for the global object
+declare global {
+    interface Window {
+        __metadataResolvers?: {
+            resolve: (metadata: Record<string, any> | null) => void;
+            item: IStoreItem;
+        };
+    }
+}

package/src/components/Store/sections/StoreItemsSection.tsx

@@ -1,12 +1,13 @@
-import { IStoreItem, UserAccountTypes } from '@rpg-engine/shared';
+import { IStoreItem, MetadataType, UserAccountTypes } from '@rpg-engine/shared';
 import React, { useState } from 'react';
 import { ScrollableContent } from '../../shared/ScrollableContent/ScrollableContent';
+import { StoreCharacterSkinRow } from '../StoreCharacterSkinRow';
 import { StoreItemRow } from '../StoreItemRow';
 
 
 interface IStoreItemsSectionProps {
   items: IStoreItem[];
-  onAddToCart: (item: IStoreItem, quantity: number) => void;
+  onAddToCart: (item: IStoreItem, quantity: number, metadata?: Record<string, any>) => void;
   atlasJSON: Record<string, any>;
   atlasIMG: string;
   userAccountType?: UserAccountTypes;
@@ -25,15 +26,33 @@ export const StoreItemsSection: React.FC<IStoreItemsSectionProps> = ({
     item.name.toLowerCase().includes(searchQuery.toLowerCase())
   );
 
-  const renderStoreItem = (item: IStoreItem) => (
-    <StoreItemRow
-      item={item}
-      atlasJSON={atlasJSON}
-      atlasIMG={atlasIMG}
-      onAddToCart={onAddToCart}
-      userAccountType={userAccountType || UserAccountTypes.Free}
-    />
-  );
+  const renderStoreItem = (item: IStoreItem) => {
+    // Use the specialized character skin row for items with character skin metadata
+    if (item.metadataType === MetadataType.CharacterSkin) {
+      return (
+        <StoreCharacterSkinRow
+          key={item._id}
+          item={item}
+          atlasJSON={atlasJSON}
+          atlasIMG={atlasIMG}
+          onAddToCart={onAddToCart}
+          userAccountType={userAccountType || UserAccountTypes.Free}
+        />
+      );
+    }
+    
+    // Use the standard item row for all other items
+    return (
+      <StoreItemRow
+        key={item._id}
+        item={item}
+        atlasJSON={atlasJSON}
+        atlasIMG={atlasIMG}
+        onAddToCart={onAddToCart}
+        userAccountType={userAccountType || UserAccountTypes.Free}
+      />
+    );
+  };
 
   return (
     <ScrollableContent

package/src/index.tsx

@@ -42,6 +42,7 @@ export * from './components/NPCDialog/QuestionDialog/QuestionDialog';
 export * from './components/PartySystem';
 export * from './components/ProgressBar';
 export * from './components/PropertySelect/PropertySelect';
+export * from './components/QuantitySelector/QuantitySelectorModal';
 export * from './components/Quests/QuestInfo/QuestInfo';
 export * from './components/Quests/QuestList';
 export * from './components/RadioButton';
@@ -55,6 +56,10 @@ export * from './components/SkillsContainer';
 export * from './components/SocialModal/SocialModal';
 export * from './components/Spellbook/Spellbook';
 export * from './components/Stepper';
+export * from './components/Store/CartView';
+export * from './components/Store/hooks/useStoreCart';
+export * from './components/Store/MetadataCollector';
+export * from './components/Store/Store';
 export * from './components/Table/Table';
 export * from './components/TextArea';
 export * from './components/TimeWidget/TimeWidget';
@@ -63,7 +68,5 @@ export * from './components/TradingMenu/TradingMenu';
 export * from './components/Truncate';
 export * from './components/Tutorial/TutorialStepper';
 export * from './components/typography/DynamicText';
-
-export * from './components/QuantitySelector/QuantitySelectorModal';
-
 export { useEventListener } from './hooks/useEventListener';
+

package/src/stories/Character/SkinSelectionGrid.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { SkinSelectionGrid } from '../../components/Character/SkinSelectionGrid';
+import { RPGUIRoot } from '../../components/RPGUI/RPGUIRoot';
+import entitiesAtlasJSON from '../../mocks/atlas/entities/entities.json';
+import entitiesAtlasIMG from '../../mocks/atlas/entities/entities.png';
+
+/**
+ * SkinSelectionGrid stories showcasing the carousel-style character skin selection component
+ */
+const meta = {
+  title: 'Character/SkinSelectionGrid',
+  component: SkinSelectionGrid,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 
+          'The SkinSelectionGrid component provides a carousel-style selection interface ' +
+          'for character skins. Users can navigate through available skins using left and right arrows.',
+      },
+    },
+  },
+  decorators: [
+    Story => (
+      <RPGUIRoot>
+        <div style={{ width: '400px', background: '#333', padding: '20px', borderRadius: '5px' }}>
+          <Story />
+        </div>
+      </RPGUIRoot>
+    ),
+  ],
+} satisfies Meta<typeof SkinSelectionGrid>;
+
+export default meta;
+type Story = StoryObj<typeof SkinSelectionGrid>;
+
+// Sample character skins
+const availableCharacters = [
+  {
+    id: 'black-knight',
+    name: 'Black Knight',
+    textureKey: 'black-knight',
+  },
+  {
+    id: 'dragon-knight',
+    name: 'Dragon Knight',
+    textureKey: 'dragon-knight',
+  },
+  {
+    id: 'senior-knight-1',
+    name: 'Senior Knight',
+    textureKey: 'senior-knight-1',
+  },
+  {
+    id: 'character-1',
+    name: 'Character 1',
+    textureKey: 'character-1',
+  },
+  {
+    id: 'character-2',
+    name: 'Character 2',
+    textureKey: 'character-2',
+  },
+  {
+    id: 'character-3',
+    name: 'Character 3',
+    textureKey: 'character-3',
+  },
+  {
+    id: 'character-4',
+    name: 'Character 4',
+    textureKey: 'character-4',
+  },
+];
+
+/**
+ * Default story showing the carousel-style skin selection with multiple character options
+ * Users can navigate through the skins using left and right arrows
+ */
+export const Default: Story = {
+  render: () => (
+    <SkinSelectionGrid
+      availableCharacters={availableCharacters}
+      initialSelectedSkin="black-knight"
+      onChange={(skinKey) => console.log('Selected skin:', skinKey)}
+      atlasJSON={entitiesAtlasJSON}
+      atlasIMG={entitiesAtlasIMG}
+    />
+  ),
+};
+
+/**
+ * Story showing the skin selection with only a few options
+ */
+export const FewOptions: Story = {
+  render: () => (
+    <SkinSelectionGrid
+      availableCharacters={availableCharacters.slice(0, 3)}
+      initialSelectedSkin="dragon-knight"
+      onChange={(skinKey) => console.log('Selected skin:', skinKey)}
+      atlasJSON={entitiesAtlasJSON}
+      atlasIMG={entitiesAtlasIMG}
+    />
+  ),
+}; 

package/src/stories/Character/character/CharacterSkinSelectionModal.stories.tsx

@@ -1,52 +1,113 @@
-import { Meta, Story } from '@storybook/react';
+import { Meta, StoryObj } from '@storybook/react';
 import React from 'react';
 import { RPGUIRoot } from '../../..';
 import {
-  CharacterSkinSelectionModal,
-  ICharacterSkinSelectionModalProps,
+    CharacterSkinSelectionModal
 } from '../../../components/Character/CharacterSkinSelectionModal';
 import atlasJSON from '../../../mocks/atlas/entities/entities.json';
 import atlasIMG from '../../../mocks/atlas/entities/entities.png';
 
-const meta: Meta = {
+/**
+ * Character skin selection modal with carousel-style navigation.
+ * This allows users to browse through available character skins using arrow buttons.
+ */
+const meta = {
   title: 'Character/Character/Skin Selection',
   component: CharacterSkinSelectionModal,
-};
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 
+          'Character Skin Selection modal with carousel-style navigation. ' +
+          'Users can browse through available skins using left and right arrows.',
+      },
+    },
+  },
+  decorators: [
+    Story => (
+      <RPGUIRoot>
+        <div style={{ background: '#333', padding: '10px', borderRadius: '5px' }}>
+          <Story />
+        </div>
+      </RPGUIRoot>
+    ),
+  ],
+} satisfies Meta<typeof CharacterSkinSelectionModal>;
 
 export default meta;
+type Story = StoryObj<typeof CharacterSkinSelectionModal>;
 
-const Template: Story<ICharacterSkinSelectionModalProps> = (
-  args: ICharacterSkinSelectionModalProps
-) => (
-  <RPGUIRoot>
-    <CharacterSkinSelectionModal {...args} />
-  </RPGUIRoot>
-);
-
-export const KnightSkins = Template.bind({});
-
-// Example of different knight skins
-const knightCharacters = [
+// Example of different character skins
+const characterSkins = [
   {
+    id: 'black-knight',
     name: 'Black Knight',
     textureKey: 'black-knight',
   },
   {
+    id: 'dragon-knight',
     name: 'Dragon Knight',
     textureKey: 'dragon-knight',
   },
   {
+    id: 'senior-knight-1',
     name: 'Senior Knight',
     textureKey: 'senior-knight-1',
   },
+  {
+    id: 'character-1',
+    name: 'Character 1',
+    textureKey: 'character-1',
+  },
+  {
+    id: 'character-2',
+    name: 'Character 2',
+    textureKey: 'character-2',
+  },
+  {
+    id: 'character-3',
+    name: 'Character 3',
+    textureKey: 'character-3',
+  },
+  {
+    id: 'character-4',
+    name: 'Character 4',
+    textureKey: 'character-4',
+  },
 ];
 
-KnightSkins.args = {
-  isOpen: true,
-  onClose: () => console.log('Modal closed'),
-  onConfirm: (textureKey: string) => console.log('Selected skin:', textureKey),
-  availableCharacters: knightCharacters,
-  atlasJSON: atlasJSON,
-  atlasIMG: atlasIMG,
-  initialSelectedSkin: 'black-knight',
+/**
+ * Default story showing the character skin selection modal with multiple options.
+ * Users can navigate through the available skins using the left and right arrows.
+ */
+export const Default: Story = {
+  render: () => (
+    <CharacterSkinSelectionModal
+      isOpen={true}
+      onClose={() => console.log('Modal closed')}
+      onConfirm={(textureKey: string) => console.log('Selected skin:', textureKey)}
+      availableCharacters={characterSkins}
+      atlasJSON={atlasJSON}
+      atlasIMG={atlasIMG}
+      initialSelectedSkin="black-knight"
+    />
+  ),
+};
+
+/**
+ * Story showing the skin selection modal with just a few options.
+ */
+export const FewOptions: Story = {
+  render: () => (
+    <CharacterSkinSelectionModal
+      isOpen={true}
+      onClose={() => console.log('Modal closed')}
+      onConfirm={(textureKey: string) => console.log('Selected skin:', textureKey)}
+      availableCharacters={characterSkins.slice(0, 3)}
+      atlasJSON={atlasJSON}
+      atlasIMG={atlasIMG}
+      initialSelectedSkin="dragon-knight"
+    />
+  ),
 };

package/src/stories/Features/store/MetadataCollector.stories.tsx

@@ -0,0 +1,94 @@
+import { MetadataType } from '@rpg-engine/shared';
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { RPGUIRoot } from '../../../components/RPGUI/RPGUIRoot';
+import { MetadataCollector } from '../../../components/Store/MetadataCollector';
+import entitiesAtlasJSON from '../../../mocks/atlas/entities/entities.json';
+import entitiesAtlasIMG from '../../../mocks/atlas/entities/entities.png';
+
+/**
+ * MetadataCollector stories showcasing different use cases for collecting metadata
+ * during the purchase flow. This component is used when a purchase requires additional
+ * user input before completing the transaction.
+ */
+const meta = {
+  title: 'Features/Store/MetadataCollector',
+  component: MetadataCollector,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 
+          'The MetadataCollector component handles collecting additional information from ' +
+          'users during the purchase flow when needed. For example, when purchasing a ' +
+          'character skin, the user needs to select which skin they want to use.',
+      },
+    },
+  },
+  decorators: [
+    Story => (
+      <RPGUIRoot>
+        <Story />
+      </RPGUIRoot>
+    ),
+  ],
+} satisfies Meta<typeof MetadataCollector>;
+
+export default meta;
+type Story = StoryObj<typeof MetadataCollector>;
+
+// Sample character skins
+const availableCharacters = [
+  {
+    id: 'black-knight',
+    name: 'Black Knight',
+    textureKey: 'black-knight',
+  },
+  {
+    id: 'dragon-knight',
+    name: 'Dragon Knight',
+    textureKey: 'dragon-knight',
+  },
+  {
+    id: 'senior-knight-1',
+    name: 'Senior Knight',
+    textureKey: 'senior-knight-1',
+  },
+];
+
+/**
+ * Story showing the Character Skin selection interface that appears
+ * when a user purchases a character skin item that requires selecting
+ * which skin to apply.
+ */
+export const CharacterSkin: Story = {
+  render: () => (
+    <MetadataCollector
+      metadataType={MetadataType.CharacterSkin}
+      config={{
+        availableCharacters,
+        atlasJSON: entitiesAtlasJSON,
+        atlasIMG: entitiesAtlasIMG,
+        initialSelectedSkin: 'black-knight',
+      }}
+      onCollect={(metadata: Record<string, any>) => console.log('Metadata collected:', metadata)}
+      onCancel={() => console.log('Metadata collection cancelled')}
+    />
+  ),
+};
+
+/**
+ * Story showing the fallback for unhandled metadata types.
+ * This demonstrates the behavior when a metadata type is requested
+ * that hasn't been implemented yet.
+ */
+export const Unhandled: Story = {
+  render: () => (
+    <MetadataCollector
+      metadataType={'unhandled-type' as MetadataType}
+      config={{}}
+      onCollect={() => console.log('Metadata collected')}
+      onCancel={() => console.log('Metadata collection cancelled')}
+    />
+  ),
+};