@instructure/outcomes-ui 4.0.0 → 4.1.0

package/es/i18n/__tests__/i18n.test.ts

@@ -0,0 +1,144 @@
+import { expect, jest, describe, it, beforeEach } from '@jest/globals'
+
+// Mock the translation loader
+jest.mock('../translationLoader', () => ({
+  loadDefaultTranslations: () => ({
+    en: {
+      test_key_1: { message: 'Test message 1' },
+      test_key_2: { message: 'Test message 2' },
+    },
+    es: {
+      test_key_1: { message: 'Mensaje de prueba 1' },
+      test_key_2: { message: 'Mensaje de prueba 2' },
+    },
+  }),
+}))
+
+// Mock format-message
+jest.mock('format-message')
+
+// Mock format-message-generate-id
+jest.mock('format-message-generate-id/underscored_crc32')
+
+// Now import
+import formatMessage, { type SetupOptions } from 'format-message'
+import { setupI18n, getAvailableLanguages, isLanguageAvailable } from '../i18n'
+
+describe('i18n', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+
+    // Setup mocks
+    const mockSetup = jest.fn()
+    ;(formatMessage.setup as unknown) = mockSetup
+  })
+
+  describe('getAvailableLanguages', () => {
+    it('returns list of available languages', () => {
+      const languages = getAvailableLanguages()
+      expect(Array.isArray(languages)).toBe(true)
+      expect(languages.length).toBeGreaterThan(0)
+      // Should include at least the languages from the translations folder
+      expect(languages).toContain('en')
+    })
+  })
+
+  describe('isLanguageAvailable', () => {
+    it('returns true for available language', () => {
+      expect(isLanguageAvailable('en')).toBe(true)
+    })
+
+    it('returns false for unavailable language', () => {
+      expect(isLanguageAvailable('xyz')).toBe(false)
+    })
+  })
+
+  describe('setupI18n', () => {
+    it('calls formatMessage.setup with correct parameters', () => {
+      setupI18n('en')
+
+      expect(formatMessage.setup).toHaveBeenCalledTimes(1)
+      const callArgs = (formatMessage.setup as jest.Mock).mock.calls[0][0] as SetupOptions
+
+      expect(callArgs.locale).toBe('en')
+      expect(callArgs.translations).toBeDefined()
+      expect(callArgs.generateId).toBeDefined()
+    })
+
+    it('merges overrides with default translations', () => {
+      const overrides = {
+        en: {
+          custom_key: { message: 'Custom message' },
+        },
+      }
+
+      setupI18n('en', overrides)
+
+      const callArgs = (formatMessage.setup as jest.Mock).mock.calls[0][0] as SetupOptions
+      const translations = callArgs.translations!
+
+      expect(translations.en!.custom_key).toEqual({ message: 'Custom message' })
+    })
+
+    it('preserves default translations when overriding', () => {
+      const overrides = {
+        en: {
+          custom_key: { message: 'Custom message' },
+        },
+      }
+
+      setupI18n('en', overrides)
+
+      const callArgs = (formatMessage.setup as jest.Mock).mock.calls[0][0] as SetupOptions
+      const translations = callArgs.translations!
+
+      // Original translations should still be present
+      expect(translations.en!.test_key_1).toBeDefined()
+      expect(translations.en!.custom_key).toEqual({ message: 'Custom message' })
+    })
+
+    it('warns when language is not available and no override provided', () => {
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
+      setupI18n('xyz')
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Language "xyz" not available')
+      )
+
+      consoleWarnSpy.mockRestore()
+    })
+
+    it('does not warn when unavailable language has override', () => {
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+
+      setupI18n('xyz', {
+        xyz: { key1: { message: 'Test' } },
+      })
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled()
+
+      consoleWarnSpy.mockRestore()
+    })
+
+    it('handles empty overrides object', () => {
+      setupI18n('en', {})
+
+      expect(formatMessage.setup).toHaveBeenCalledTimes(1)
+      const callArgs = (formatMessage.setup as jest.Mock).mock.calls[0][0] as SetupOptions
+
+      expect(callArgs.locale).toBe('en')
+      expect(callArgs.translations).toBeDefined()
+    })
+
+    it('handles undefined overrides', () => {
+      setupI18n('en', undefined)
+
+      expect(formatMessage.setup).toHaveBeenCalledTimes(1)
+      const callArgs = (formatMessage.setup as jest.Mock).mock.calls[0][0] as SetupOptions
+
+      expect(callArgs.locale).toBe('en')
+      expect(callArgs.translations).toBeDefined()
+    })
+  })
+})

package/es/i18n/format-message-generate-id.d.ts

@@ -0,0 +1,4 @@
+declare module 'format-message-generate-id/underscored_crc32' {
+  function underscoredCrc32(pattern: string): string
+  export = underscoredCrc32
+}

package/es/i18n/i18n.ts

@@ -0,0 +1,64 @@
+// i18n.ts
+// Translation wrapper for format-message with override support
+
+import formatMessage, { type Translations } from 'format-message'
+import underscoredCrc32 from 'format-message-generate-id/underscored_crc32'
+import { loadDefaultTranslations } from './translationLoader'
+
+const defaultTranslations = loadDefaultTranslations()
+
+/**
+ * Utility to merge default and override translations for all languages.
+ */
+function getMergedTranslations(overrides?: Translations): Translations {
+  const merged: Translations = { ...defaultTranslations }
+
+  if (overrides) {
+    for (const language in overrides) {
+      const langOverrides = overrides[language]
+
+      if (langOverrides && typeof langOverrides === 'object') {
+        merged[language] = merged[language]
+          ? { ...merged[language], ...langOverrides }
+          : langOverrides
+      }
+    }
+  }
+
+  return merged
+}
+
+/**
+ * Get list of available languages.
+ */
+export function getAvailableLanguages(): string[] {
+  return Object.keys(defaultTranslations)
+}
+
+/**
+ * Check if a language is available.
+ */
+export function isLanguageAvailable(language: string): boolean {
+  return language in defaultTranslations
+}
+
+/**
+ * Setup format-message for a given language and resource overrides.
+ *
+ * @param language - The current language code (e.g., 'en', 'es')
+ * @param overrides - Optional resource overrides for any language (nested structure: { lang: { key: "text" } })
+ * @throws {Error} If the language is not available and no overrides are provided
+ */
+export function setupI18n(language: string, overrides?: Translations): void {
+  if (!isLanguageAvailable(language) && !overrides?.[language]) {
+    console.warn(`Language "${language}" not available. Available: ${getAvailableLanguages().join(', ')}`)
+  }
+
+  const translations = getMergedTranslations(overrides)
+
+  formatMessage.setup({
+    locale: language,
+    translations,
+    generateId: underscoredCrc32,
+  })
+}

package/es/i18n/translationLoader.ts

@@ -0,0 +1,22 @@
+import { type Translations } from 'format-message'
+
+/**
+ * Load translation files using webpack's require.context.
+ */
+export function loadTranslationContext() {
+  return require.context('../../translations', false, /\.json$/)
+}
+
+/**
+ * Load and build the default translations object from all translation files.
+ */
+export function loadDefaultTranslations(): Readonly<Translations> {
+  const translationContext = loadTranslationContext()
+
+  return Object.freeze(
+    translationContext.keys().reduce((acc, fileName) => {
+      const languageCode = fileName.replace(/^\.\//, '').replace(/\.json$/, '')
+      return { ...acc, [languageCode]: translationContext(fileName) }
+    }, {} as Translations)
+  )
+}

package/es/jest-dom.d.ts

@@ -0,0 +1,10 @@
+import type {TestingLibraryMatchers} from '@testing-library/jest-dom/matchers'
+import type {expect} from '@jest/globals'
+
+declare module '@jest/expect' {
+  interface Matchers<R extends void | Promise<void>>
+    extends TestingLibraryMatchers<
+      ReturnType<typeof expect.stringContaining>,
+      R
+    > {}
+}

package/es/test/jest-setup/__mocks__/msw-storybook-addon.js

@@ -0,0 +1,15 @@
+/* eslint-env jest */
+// Mock for msw-storybook-addon in Jest environment
+// Storybook MSW integration is not needed in Jest tests
+
+// Provide a default export as well for ES6 imports
+var mswStorybook = {
+  initialize: jest.fn(),
+  mswLoader: jest.fn(function () {
+    return {};
+  })
+};
+module.exports = mswStorybook;
+module.exports.initialize = mswStorybook.initialize;
+module.exports.mswLoader = mswStorybook.mswLoader;
+module.exports.default = mswStorybook;

package/es/test/jest-setup/__mocks__/msw.js

@@ -0,0 +1,58 @@
+/* eslint-env jest */
+// Mock for msw in Jest environment
+// MSW is used in Storybook but not needed in Jest snapshot tests
+
+var HttpResponse = {
+  json: jest.fn(function (data, options) {
+    return {
+      data: data,
+      options: options
+    };
+  }),
+  text: jest.fn(function (text, options) {
+    return {
+      text: text,
+      options: options
+    };
+  })
+};
+var http = {
+  get: jest.fn(function () {
+    return jest.fn();
+  }),
+  post: jest.fn(function () {
+    return jest.fn();
+  }),
+  put: jest.fn(function () {
+    return jest.fn();
+  }),
+  patch: jest.fn(function () {
+    return jest.fn();
+  }),
+  delete: jest.fn(function () {
+    return jest.fn();
+  }),
+  all: jest.fn(function () {
+    return jest.fn();
+  })
+};
+var setupWorker = jest.fn(function () {
+  return {
+    start: jest.fn(),
+    stop: jest.fn(),
+    use: jest.fn()
+  };
+});
+var setupServer = jest.fn(function () {
+  return {
+    listen: jest.fn(),
+    close: jest.fn(),
+    use: jest.fn()
+  };
+});
+module.exports = {
+  http: http,
+  HttpResponse: HttpResponse,
+  setupWorker: setupWorker,
+  setupServer: setupServer
+};

package/es/translated/ar/components/FlashAlert/index.d.ts

@@ -0,0 +1,11 @@
+export interface ShowFlashAlertProps {
+  message: string
+  err?: Error | unknown
+  type?: 'info' | 'success' | 'warning' | 'error'
+  timeout?: number
+  srOnly?: boolean
+}
+
+export function showFlashAlert(props: ShowFlashAlertProps): void
+
+export declare const defaultTimeout: number

package/es/translated/ar/components/Gradebook/GradebookApp.stories.tsx

@@ -0,0 +1,98 @@
+import React from 'react'
+import GradebookApp, { type GradebookAppProps } from './index'
+import { type Translations } from 'format-message'
+import type { Meta, StoryObj } from '@storybook/react'
+import { action } from '@storybook/addon-actions'
+import type { GradebookConfig } from './context/GradebookConfigContext'
+import type { SaveSettingsResult } from './context/GradebookAppContext'
+
+// Example minimal settings type
+interface ExampleSettings {
+  option1: boolean
+}
+
+const meta: Meta<typeof GradebookApp<ExampleSettings>> = {
+  title: 'Gradebook/GradebookApp',
+  component: GradebookApp,
+}
+
+export default meta
+
+type Story = StoryObj<GradebookAppProps<ExampleSettings>>
+
+const defaultConfig: GradebookConfig<ExampleSettings> = {
+  components: {
+    StudentPopover: () => <div>Student Popover</div>,
+    SettingsTrayContent: () => <div>Settings Content</div>,
+  },
+}
+
+const defaultSettings = {
+  settings: {
+    option1: true,
+  },
+  onSave: async (settings: ExampleSettings): Promise<SaveSettingsResult> => {
+    action('onSave')(settings)
+    await new Promise(resolve => setTimeout(resolve, 1000))
+    return { success: true }
+  },
+}
+
+const resourceOverrides: Translations = {
+  en: {
+    'align_new_outcomes_2a2d3d48': 'Align new outcomes',
+    'failed_to_load_user_details_7221befa': 'Failed to load user details',
+    'loading_user_details_53ede5bb': 'Loading user details',
+    'message_5c38209d': 'Message',
+    'student_details_for_cc4a4206': 'Student Details',
+    'view_mastery_report_7b7c9bc7': 'View Mastery Report',
+    'export_de71cd8e': 'Export',
+    'error_exporting_gradebook_b6558e60': 'Error exporting gradebook',
+    'count_plural_one_one_option_available_other_option_e3576eb7': '{ count, plural,\n    one {One option available.}\n  other {# options available.}\n}',
+    'label_removed_436b4303': '{ label } removed.',
+    'label_selected_list_collapsed_8af3a06b': '{ label } selected. List collapsed.',
+    'no_result_found_3d3fc3e3': 'No result found',
+    'type_or_use_arrow_keys_to_navigate_multiple_select_ec56e29c': 'Type or use arrow keys to navigate. Multiple selections are allowed.',
+    'alphabetical_55b5b4e0': 'Alphabetical',
+    'arrange_outcomes_by_686d3753': 'Arrange Outcomes by',
+    'avatars_in_student_list_59c74330': 'Avatars in student list',
+    'close_settings_tray_7b3084c2': 'Close Settings Tray',
+    'custom_6979cd81': 'Custom',
+    'display_e6546241': 'Display',
+    'first_name_last_name_2ae30a4b': 'First Name Last Name',
+    'icons_descriptor_32dde915': 'Icons + Descriptor',
+    'icons_only_f3ac5009': 'Icons Only',
+    'icons_points_987265a4': 'Icons + Points',
+    'integration_id_8a20b328': 'Integration ID',
+    'last_name_first_name_f3796e59': 'Last Name, First Name',
+    'login_id_12109693': 'Login ID',
+    'name_display_format_c61848ad': 'Name Display Format',
+    'none_3b5e34d2': 'None',
+    'outcomes_with_no_results_7fbb5bb5': 'Outcomes with no results',
+    'save_11a80ec3': 'Save',
+    'scoring_91f3b228': 'Scoring',
+    'secondary_info_835a07dd': 'Secondary info',
+    'settings_5aa0fd0c': 'Settings',
+    'settings_tray_d3fa9e57': 'Settings Tray',
+    'sis_id_4495a887': 'SIS ID',
+    'students_with_no_results_6bd5424b': 'Students with no results',
+    'there_was_an_error_saving_your_settings_please_try_4fded25e': 'There was an error saving your settings. Please try again.',
+    'unpublished_assignments_9cdbcc87': 'Unpublished Assignments',
+    'upload_order_513421ce': 'Upload Order',
+    'you_may_drag_drop_columns_to_re_arrange_bdb837da': '(You may drag & drop columns to re-arrange)',
+    'your_settings_have_been_saved_aa46c66c': 'Your settings have been saved.',
+    'view_contributing_score_details_7bc242ac': 'View Contributing Score Details',
+  },
+}
+
+export const Default: Story = {
+  args: {
+    config: defaultConfig,
+    settings: defaultSettings,
+    translations: {
+      language: 'en',
+      resourceOverrides,
+      i18nEnabled: true,
+    },
+  },
+}

package/es/translated/ar/components/Gradebook/README.md

@@ -0,0 +1,77 @@
+# Gradebook Component
+
+This folder contains the main entry point for the Outcomes UI package LMGB integration.
+
+## Components
+
+-   **GradebookApp**: The root React component to be imported and rendered by the consuming project.
+
+## Usage
+
+Import and render `GradebookApp` in your project:
+
+```tsx
+import { GradebookApp } from "@instructure/outcomes-ui/src/components/Gradebook";
+
+<GradebookApp
+    config={{
+        components: {
+            StudentPopover: MyStudentPopover,
+            SettingsTrayContent: MySettings,
+        },
+    }}
+    settings={{
+        settings: mySettings,
+        onSave: handleSaveSettings,
+    }}
+    translations={{
+        language: "en",
+        resourceOverrides: { en: { key: "value" } },
+        i18nEnabled: true,
+    }}
+/>;
+```
+
+### Props
+
+#### config
+
+-   `components` (object): Required components for the gradebook.
+    -   `StudentPopover`: Component for displaying student details
+    -   `SettingsTrayContent`: Component for rendering settings form fields
+-   `masteryLevelConfig` (object): Optional mastery level configuration.
+
+#### settings
+
+-   `settings` (TSettings): The current settings object.
+-   `onSave` (function): Handler that persists settings, returns Promise<SaveSettingsResult>.
+
+#### translations
+
+-   `language` (string): The current language code (required if `i18nEnabled` is true or omitted).
+-   `resourceOverrides` (object): Optional translation overrides for any language.
+-   `i18nEnabled` (boolean): Enable or disable i18n. If `false`, language and resourceOverrides are ignored.
+
+## Best Practices
+
+-   Memoize `resourceOverrides` in the consuming project to avoid unnecessary rerenders.
+-   Pass the current language and overrides explicitly from your app's state or context.
+
+### Example
+
+```tsx
+const overrides = useMemo(() => ({ en: { hello: 'Hi!' } }), [])
+
+<GradebookApp
+  config={myGradebookConfig}
+  settings={{
+    settings: mySettings,
+    onSave: handleSaveSettings
+  }}
+  translations={{
+    language: 'en',
+    resourceOverrides: overrides,
+    i18nEnabled: true,
+  }}
+/>
+```