@moises.ai/design-system 3.4.5 → 3.5.0

package/src/components/StemGenerationForm/StemGenerationForm.stories.jsx

@@ -0,0 +1,703 @@
+import { StemGenerationForm } from './StemGenerationForm'
+import { FORM_DEFAULTS } from './utils'
+
+export default {
+  title: 'Extensions/StemGenerationForm',
+  component: StemGenerationForm,
+  decorators: [
+    (Story) => (
+      <div style={{ width: '400px', height: '600px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+
+A comprehensive form component for AI stem generation with support for both preset-based and custom generation modes.
+
+---
+
+## Basic Usage
+
+\`\`\`jsx
+import { StemGenerationForm } from '@moises.ai/design-system'
+
+<StemGenerationForm
+  formState={formState}
+  onFormStateChange={setFormState}
+  presets={presets}
+  i18n={i18n}
+  onSubmit={handleSubmit}
+  unmutedTracksCount={3}
+/>
+\`\`\`
+
+
+---
+
+## Component API
+
+###  Props
+
+| Prop | Description |
+|------|-------------|
+| \`formState\` | Current form state containing all generation parameters. |
+| \`onFormStateChange\` | Callback to update form state. Can accept a new state object or updater function. |
+| \`presets\` | Array of preset configurations for quick generation. |
+| \`onAddConditioningAudio\` | Callback to open file picker for reference audio. |
+| \`showConditioningTextPaywall\` | Function to show paywall when accessing text conditioning (pro feature). |
+| \`showAdvancedControlsPaywall\` | Function to show paywall for advanced creative controls (pro feature). |
+| \`i18n\` | Internationalization object with _ method for translations. |
+| \`onSubmit\` | Callback fired when the "Generate Stem" button is clicked. |
+| \`limitReached\` | Whether generation concurrency limit has been reached. |
+| \`showUpgradeConcurrency\` | Shows upgrade button when limit is reached.  |
+| \`onClickUpgradeConcurrency\` | Callback for upgrade button click on concurrency component. |
+| \`error\` | Error message to display with clear button. |
+| \`generateFromTrack\` | Track to use as context for generation. |
+| \`inpaintingTrack\` | Track being used for inpainting. |
+| \`generateFromSelectionTrack\` | Track with selection for generation. |
+| \`unmutedTracksCount\` | Number of unmuted tracks. Button disabled if 0. |
+| \`onMountConcurrency\` | Callback fired when concurrency component mounts. |
+| \`onClear\` | Callback to clear generation state. |
+
+### Definitions
+
+\`\`\`jsx
+
+preset = {
+  description: string;
+  id: string;
+  instrument: string;
+  instrumentType: string;
+  name: string;
+  presetName: string;
+}
+
+formState = {
+  steps: number;
+  guidanceScale: number | null;
+  autoGuidanceScale: boolean;
+  instrument: string;
+  chroma: number | null;
+  clapNn: boolean;
+  conditioningText: string;
+  conditioningAudio: ArrayBuffer | null;
+  presetId: string | null;
+  guidanceClap: number | null;
+  guidanceContextAudio: number | null;
+  guidanceContextChroma: number | null;
+  useProjectChords: boolean;
+  contextAudio: ArrayBuffer | null;
+  weightSchedule: number | null;
+  presetName: string;
+  presetNameLocalized: string;
+  trackName: string | null;
+}
+
+
+inpaintingTrack = {
+  trackId: string;
+  from: number;
+  to: number;
+  name: string;
+  position: number;
+  arrayBuffer: ArrayBuffer;
+  groupId: string;
+}
+
+generateFromSelectionTrack = {
+  trackId: string;
+  from: number;
+  to: number;
+  name: string;
+  position: number;
+  arrayBuffer: ArrayBuffer;
+  groupId: string;
+}
+
+
+generateFromTrack = {
+  id: string;
+  groupId: string;
+  name: string;
+  position: number;
+  pan: number;
+  volume: number;
+  isSolo: boolean;
+  isMuted: boolean;
+  duration: number;
+  loading: boolean;
+  isStitched: boolean;
+  startPositionMs: number;
+  infos: {
+    source: string;
+  };
+}
+\`\`\`
+
+---
+
+## Notes
+
+- The form automatically switches between "Preset" and "Custom" modes
+- Generate button is disabled when: no unmuted tracks, no preset selected (preset mode), or no text/audio (custom mode)
+- When there are no presets for the selected instrument, the custom form is shown
+- Drums instrument does not support harmonic guidance (chroma)
+- Error and Success messages auto-dismiss after 3 seconds
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    formState: {
+      description: 'Current form state containing all generation parameters',
+      control: false,
+    },
+    onFormStateChange: {
+      description: 'Callback fired when form state changes',
+      control: false,
+    },
+    presets: {
+      description: 'Array of preset configurations for quick generation',
+      control: false,
+    },
+    onAddConditioningAudio: {
+      description: 'Callback to open file picker for reference audio',
+      control: false,
+    },
+    showConditioningTextPaywall: {
+      description:
+        'Function to show paywall when accessing text conditioning (premium feature)',
+      control: false,
+    },
+    showAdvancedControlsPaywall: {
+      description: 'Function to show paywall for advanced creative controls',
+      control: false,
+    },
+    i18n: {
+      description: 'Internationalization object with _ method for translations',
+      control: false,
+    },
+    loading: {
+      description: 'Loading state during generation',
+      control: false,
+    },
+    onSubmit: {
+      description: 'Callback fired when generate button is clicked',
+      control: false,
+    },
+    limitReached: {
+      description: 'Whether generation concurrency limit has been reached',
+      control: false,
+    },
+    showUpgradeConcurrency: {
+      description: 'Whether to show upgrade button when limit is reached',
+      control: false,
+    },
+    onClickUpgradeConcurrency: {
+      description: 'Callback for upgrade button click',
+      control: false,
+    },
+    error: {
+      description: 'Error message to display',
+      control: false,
+    },
+    generateFromTrack: {
+      description: 'Track object to generate from (context generation)',
+      control: false,
+    },
+    inpaintingTrack: {
+      description: 'Track being used for inpainting',
+      control: false,
+    },
+    generateFromSelectionTrack: {
+      description: 'Track with selection for generation',
+      control: false,
+    },
+    unmutedTracksCount: {
+      description: 'Number of unmuted tracks in the project',
+      control: false,
+    },
+    onMountConcurrency: {
+      description: 'Callback fired when concurrency component mounts',
+      control: false,
+    },
+    onClear: {
+      description: 'Callback to clear generation state',
+      control: false,
+    },
+  },
+}
+
+// Mock presets data - matching real-world usage
+const mockPresets = [
+  {
+    id: 'feeling-lucky-drums-01',
+    instrument: 'drums',
+    instrumentType: 'DRUMS',
+    name: 'AI Suggestion',
+    presetName: 'AI Match',
+    description: 'Generate a drum track from audio context.',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+  {
+    id: 'drums-rock-1',
+    instrument: 'drums',
+    instrumentType: 'DRUMS',
+    name: 'Rock Drums',
+    presetName: 'rock_drums',
+    description: 'Powerful rock drum patterns',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+  {
+    id: 'feeling-lucky-bass-01',
+    instrument: 'bass',
+    instrumentType: 'BASS',
+    name: 'AI Suggestion',
+    presetName: 'AI Match',
+    description: 'Generate a bass track from audio context.',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+  {
+    id: 'bass-funky-1',
+    instrument: 'bass',
+    instrumentType: 'BASS',
+    name: 'Funky Bass',
+    presetName: 'funky_bass',
+    description: 'Groovy funk bass lines',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+  {
+    id: 'feeling-lucky-guitar-01',
+    instrument: 'guitar',
+    instrumentType: 'GUITAR',
+    name: 'AI Suggestion',
+    presetName: 'AI Match',
+    description: 'Generate a guitar track from audio context.',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+  {
+    id: 'guitar-acoustic-1',
+    instrument: 'guitar',
+    instrumentType: 'GUITAR',
+    name: 'Acoustic Guitar',
+    presetName: 'acoustic_guitar',
+    description: 'Natural acoustic guitar tones',
+    thumbnail: 'https://via.placeholder.com/80',
+  },
+]
+
+// Mock i18n object (English)
+const mockI18n = {
+  _: (text) => text,
+}
+
+// Mock i18n object (Portuguese) - for localized examples
+const mockI18nPt = {
+  _: (text) => {
+    const translations = {
+      Presets: 'Predefinições',
+      Custom: 'Personalizado',
+      'Generate Stem': 'Gerar Stem',
+      'AI Suggestion': 'Sugestão da IA',
+      'Select Reference Audio': 'Selecionar Áudio de Referência',
+      'A new track has been added to your project!':
+        'Uma nova faixa foi adicionada ao seu projeto!',
+      'An error occurred while generating the track. Please try again.':
+        'Ocorreu um erro ao gerar a faixa. Por favor, tente novamente.',
+      Clear: 'Limpar',
+    }
+    return translations[text] || text
+  },
+}
+
+/**
+ * ## Default State
+ *
+ * The form in its initial state with no track selected and default settings.
+ * Ready for user to start configuring generation parameters.
+ */
+export const Default = {
+  args: {
+    formState: FORM_DEFAULTS,
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## With Preset Selected
+ *
+ * Form with a preset already selected, showing how the UI updates
+ * when user chooses a quick-start template.
+ */
+export const WithPresetSelected = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      presetId: 'drums-rock-1',
+      presetName: 'rock_drums',
+      presetNameLocalized: 'Rock Drums',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Loading State
+ *
+ * Shows the form while a stem is being generated.
+ * The generate button displays a loading spinner and is disabled.
+ */
+export const Loading = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      presetId: 'drums-rock-1',
+      conditioningText: 'Energetic rock drums with heavy kick',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: true,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Error State
+ *
+ * Displays an error message when generation fails.
+ * User can clear the error and try again.
+ */
+export const WithError = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      presetId: 'drums-rock-1',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: 'Generation failed. Please try again.',
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Limit Reached
+ *
+ * Shows the concurrency limit warning when user has reached
+ * their maximum concurrent generations. Free users see an upgrade prompt.
+ */
+export const LimitReached = {
+  args: {
+    formState: FORM_DEFAULTS,
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: true,
+    showUpgradeConcurrency: true,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Generate from Track
+ *
+ * Context-aware generation where a track is selected as context.
+ * The form displays information about the source track.
+ */
+export const GenerateFromTrack = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      presetId: 'bass-funky-1',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    generateFromTrack: {
+      id: 'track-1',
+      name: 'Main Melody',
+      duration: 180,
+    },
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Inpainting Mode
+ *
+ * Shows the form when user is replacing or modifying part of an existing track.
+ */
+export const InpaintingMode = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'guitar',
+      conditioningText: 'Smooth jazz guitar solo',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    inpaintingTrack: {
+      trackId: 'track-2',
+      from: 3.278797370617696,
+      to: 11.241590984974959,
+      name: 'Guitar Track',
+      position: 2,
+      arrayBuffer: new ArrayBuffer(1024),
+      groupId: 'default',
+    },
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Custom Generation Mode
+ *
+ * Form showing custom generation with text prompt and reference audio.
+ * Advanced creative controls can be enabled for fine-tuning.
+ */
+export const CustomGenerationWithAudio = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'bass',
+      conditioningText: 'Deep funky bass with slap technique',
+      conditioningAudio: new ArrayBuffer(1024),
+      conditioningAudioName: 'reference-bass.wav',
+      conditioningAudioSize: 2048000,
+      conditioningAudioDuration: 120,
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## No Unmuted Tracks
+ *
+ * Shows disabled state when no tracks are unmuted in the project.
+ * Generation button is disabled until at least one track is unmuted.
+ */
+export const NoUnmutedTracks = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      presetId: 'drums-rock-1',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 0,
+  },
+}
+
+/**
+ * ## Different Instruments
+ *
+ * Examples of the form configured for different instrument types.
+ * Each instrument may have different presets and options.
+ */
+export const GuitarInstrument = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'guitar',
+      presetId: 'guitar-acoustic-1',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+export const BassInstrument = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'bass',
+      presetId: 'bass-funky-1',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## AI Match Preset
+ *
+ * The special "AI Match" preset that generates stems based on audio context.
+ * This is the "feeling lucky" option that uses AI to determine the best generation parameters.
+ */
+export const AIMatchPreset = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'drums',
+      presetId: 'feeling-lucky-drums-01',
+      presetName: 'AI Match',
+      presetNameLocalized: 'AI Suggestion',
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Portuguese Localization
+ *
+ * Example showing the component with Portuguese translations.
+ * Demonstrates how i18n integration works with the component.
+ */
+export const PortugueseLocale = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'drums',
+      presetId: 'feeling-lucky-drums-01',
+      presetName: 'AI Match',
+      presetNameLocalized: 'Sugestão da IA',
+    },
+    presets: [
+      {
+        id: 'feeling-lucky-drums-01',
+        instrument: 'drums',
+        instrumentType: 'DRUMS',
+        name: 'Sugestão da IA',
+        presetName: 'AI Match',
+        description: 'Gere uma faixa de bateria a partir do contexto sonoro.',
+        thumbnail: 'https://via.placeholder.com/80',
+      },
+    ],
+    i18n: mockI18nPt,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Empty Presets (Fallback to Custom)
+ *
+ * Shows the custom form when there are no presets for the selected instrument.
+ * This is a common scenario during initial app load when presets are fetched asynchronously.
+ */
+export const EmptyPresets = {
+  args: {
+    formState: FORM_DEFAULTS,
+    presets: [],
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Custom Mode Active
+ *
+ * Shows the form in custom mode with a text prompt.
+ * This demonstrates the flexibility of creating custom stems without presets.
+ */
+export const CustomModeWithText = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'drums',
+      conditioningText:
+        'Heavy rock drums with double bass pedal and strong snare hits',
+      presetId: null,
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}
+
+/**
+ * ## Advanced Creative Controls
+ *
+ * Shows the form with advanced creative freedom controls enabled.
+ * These controls allow fine-tuning of guidance scales for more precise generation.
+ */
+export const WithCreativeControls = {
+  args: {
+    formState: {
+      ...FORM_DEFAULTS,
+      instrument: 'guitar',
+      conditioningText: 'Smooth jazz guitar with warm tone',
+      customizeCreativeFreedom: true,
+      guidanceClap: 6,
+      guidanceContextAudio: 6,
+      guidanceContextChroma: 6,
+      useProjectChords: true,
+    },
+    presets: mockPresets,
+    i18n: mockI18n,
+    loading: false,
+    limitReached: false,
+    showUpgradeConcurrency: false,
+    error: null,
+    unmutedTracksCount: 3,
+  },
+}

package/src/components/StemGenerationForm/utils/constants.js

@@ -0,0 +1,26 @@
+export const FORM_DEFAULTS = {
+  steps: 30,
+  guidanceScale: null,
+  autoGuidanceScale: true,
+  instrument: 'generic',
+  chroma: null,
+  clapNn: true,
+  conditioningText: '',
+  conditioningAudio: null,
+  presetId: null,
+  // Creative Control sliders (when enabled)
+  guidanceClap: null, // Conditioning strictness (clap)
+  guidanceContextAudio: null, // Context strictness (context_audio)
+  guidanceContextChroma: null, // Harmonic strictness (context_chroma)
+  useProjectChords: false, // Use project chords for generation
+}
+
+export const GUIDANCE_SCALE_DEFAULTS = {
+  generic: { clap: 4, context: 4, chroma: 4 },
+  bass: { clap: 2, context: 2, chroma: 2 },
+  guitar: { clap: 2, context: 2, chroma: 2 },
+  strings: { clap: 2, context: 2, chroma: 2 },
+  keys: { clap: 2, context: 2, chroma: 2 },
+  // Drums does not support chroma/harmonic guidance
+  drums: { clap: 2, context: 2, chroma: 0 },
+}