@shellui/core 0.2.0 → 0.3.0-beta.0

package/src/features/settings/utils/buildSettingsForPropagation.spec.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Settings } from '@shellui/sdk';
+import type { ShellUIConfig } from '../../config/types';
+import { buildSettingsForPropagation } from './buildSettingsForPropagation';
+
+const baseSettings: Settings = {
+  developerFeatures: { enabled: false },
+  errorReporting: { enabled: true },
+  logging: { namespaces: { shellsdk: false, shellcore: false } },
+  appearance: {
+    name: 'default',
+    displayName: 'Default',
+    mode: 'light',
+    colorScheme: 'light',
+    colors: {
+      light: {
+        background: '#fff',
+        foreground: '#000',
+        card: '#fff',
+        cardForeground: '#000',
+        popover: '#fff',
+        popoverForeground: '#000',
+        primary: '#000',
+        primaryForeground: '#fff',
+        secondary: '#eee',
+        secondaryForeground: '#000',
+        muted: '#eee',
+        mutedForeground: '#333',
+        accent: '#eee',
+        accentForeground: '#000',
+        destructive: '#f00',
+        destructiveForeground: '#fff',
+        border: '#ccc',
+        input: '#ccc',
+        ring: '#000',
+        radius: '0.5rem',
+        sidebarBackground: '#fff',
+        sidebarForeground: '#000',
+        sidebarPrimary: '#000',
+        sidebarPrimaryForeground: '#fff',
+        sidebarAccent: '#eee',
+        sidebarAccentForeground: '#000',
+        sidebarBorder: '#ccc',
+        sidebarRing: '#000',
+      },
+      dark: {
+        background: '#000',
+        foreground: '#fff',
+        card: '#000',
+        cardForeground: '#fff',
+        popover: '#000',
+        popoverForeground: '#fff',
+        primary: '#fff',
+        primaryForeground: '#000',
+        secondary: '#111',
+        secondaryForeground: '#fff',
+        muted: '#111',
+        mutedForeground: '#ddd',
+        accent: '#111',
+        accentForeground: '#fff',
+        destructive: '#900',
+        destructiveForeground: '#fff',
+        border: '#333',
+        input: '#333',
+        ring: '#fff',
+        radius: '0.5rem',
+        sidebarBackground: '#000',
+        sidebarForeground: '#fff',
+        sidebarPrimary: '#fff',
+        sidebarPrimaryForeground: '#000',
+        sidebarAccent: '#111',
+        sidebarAccentForeground: '#fff',
+        sidebarBorder: '#333',
+        sidebarRing: '#fff',
+      },
+    },
+  },
+  language: { code: 'en' },
+  region: { timezone: 'UTC' },
+  cookieConsent: { acceptedHosts: [], consentedCookieHosts: [] },
+  serviceWorker: { enabled: true },
+  user: null,
+};
+
+describe('buildSettingsForPropagation', () => {
+  it('adds localized navigation items and available themes', () => {
+    vi.stubGlobal('window', {
+      location: { origin: 'https://shellui.dev' },
+      matchMedia: () => ({ matches: false }),
+    });
+
+    const config = {
+      navigation: [
+        {
+          title: 'Main',
+          items: [
+            {
+              label: { en: 'Docs', fr: 'Docs FR' },
+              path: '/docs',
+              url: '/docs',
+            },
+          ],
+        },
+      ],
+    } as ShellUIConfig;
+
+    const result = buildSettingsForPropagation(baseSettings, config, 'fr');
+
+    expect(result.navigation?.items).toEqual([
+      {
+        path: '/docs',
+        url: '/docs',
+        label: 'Docs FR',
+      },
+    ]);
+    expect(result.appearance?.availableThemes?.length).toBeGreaterThan(0);
+  });
+
+  it('injects access token into settings.user only when explicitly allowed', () => {
+    const settingsWithUser: Settings = {
+      ...baseSettings,
+      user: {
+        id: 'u1',
+        email: 'dev@shellui.dev',
+        name: 'Dev User',
+        profilePicture: null,
+        authProvider: 'github',
+      },
+    };
+
+    const safeResult = buildSettingsForPropagation(settingsWithUser, undefined, 'en', {
+      includeAuthAccessToken: true,
+      accessToken: 'jwt.safe.token',
+    });
+    expect(safeResult.accessToken).toBe('jwt.safe.token');
+
+    const unsafeResult = buildSettingsForPropagation(settingsWithUser, undefined, 'en', {
+      includeAuthAccessToken: false,
+      accessToken: 'jwt.should.not.be.exposed',
+    });
+    expect(unsafeResult.accessToken).toBeNull();
+  });
+});

package/src/features/settings/utils/buildSettingsForPropagation.ts

@@ -0,0 +1,55 @@
+import type { Settings, SettingsNavigationItem } from '@shellui/sdk';
+import type { ShellUIConfig } from '../../config/types';
+import { flattenNavigationItems } from './flattenNavigationItems';
+import { getAvailableThemesForSettings } from './getAvailableThemesForSettings';
+import { getResolvedAppearanceForSettings } from './getResolvedAppearanceForSettings';
+import { resolveLabel } from './resolveLabel';
+
+/**
+ * Build settings for propagation to iframes: inject navigation, full theme object,
+ * and list of available themes so apps can render theme pickers.
+ */
+export const buildSettingsForPropagation = (
+  settings: Settings,
+  config: ShellUIConfig | undefined,
+  lang: string,
+  options?: {
+    includeAuthAccessToken?: boolean;
+    accessToken?: string | null;
+  },
+): Settings => {
+  const appearance = getResolvedAppearanceForSettings(settings, config);
+  let result: Settings = {
+    ...settings,
+    appearance: appearance ?? settings.appearance,
+  };
+
+  // Inject available themes when we have a resolved appearance (themes are already registered above)
+  if (result.appearance && typeof window !== 'undefined') {
+    result = {
+      ...result,
+      appearance: {
+        ...result.appearance,
+        availableThemes: getAvailableThemesForSettings(),
+      },
+    };
+  }
+
+  if (config?.navigation?.length) {
+    const items: SettingsNavigationItem[] = flattenNavigationItems(config.navigation).map(
+      (item) => ({
+        path: item.path,
+        url: item.url,
+        label: resolveLabel(item.label, lang),
+      }),
+    );
+    result = { ...result, navigation: { items } };
+  }
+
+  result = {
+    ...result,
+    accessToken: options?.includeAuthAccessToken ? (options.accessToken ?? null) : null,
+  };
+
+  return result;
+};

package/src/features/settings/utils/flattenNavigationItems.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import type { NavigationGroup, NavigationItem } from '../../config/types';
+import { flattenNavigationItems } from './flattenNavigationItems';
+
+describe('flattenNavigationItems', () => {
+  it('returns empty list when navigation is empty', () => {
+    expect(flattenNavigationItems([])).toEqual([]);
+  });
+
+  it('flattens grouped and standalone navigation items', () => {
+    const docsItem: NavigationItem = { label: 'Docs', path: '/docs', url: '/docs' };
+    const blogItem: NavigationItem = { label: 'Blog', path: '/blog', url: '/blog' };
+    const group: NavigationGroup = { title: 'Group', items: [docsItem] };
+
+    expect(flattenNavigationItems([group, blogItem])).toEqual([docsItem, blogItem]);
+  });
+});

package/src/features/settings/utils/flattenNavigationItems.ts

@@ -0,0 +1,12 @@
+import type { NavigationGroup, NavigationItem } from '../../config/types';
+
+export const flattenNavigationItems = (
+  navigation: (NavigationItem | NavigationGroup)[],
+): NavigationItem[] => {
+  if (navigation.length === 0) return [];
+
+  return navigation.flatMap((item) => {
+    if ('title' in item && 'items' in item) return item.items;
+    return [item];
+  });
+};

package/src/features/settings/utils/getAvailableThemesForSettings.spec.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { getAvailableThemesForSettings } from './getAvailableThemesForSettings';
+
+describe('getAvailableThemesForSettings', () => {
+  it('returns registered themes in the lightweight settings shape', () => {
+    const themes = getAvailableThemesForSettings();
+
+    expect(themes.length).toBeGreaterThan(0);
+    expect(themes[0]).toMatchObject({
+      name: expect.any(String),
+      displayName: expect.any(String),
+      colors: expect.any(Object),
+    });
+  });
+});

package/src/features/settings/utils/getAvailableThemesForSettings.ts

@@ -0,0 +1,16 @@
+import type { SettingsAvailableTheme } from '@shellui/sdk';
+import { getAllThemes } from '../../theme/themes';
+
+/**
+ * Map registered themes to the slim shape sent to sub-apps
+ * (name, displayName, colors, optional typography for preview).
+ */
+export const getAvailableThemesForSettings = (): SettingsAvailableTheme[] =>
+  getAllThemes().map((theme) => ({
+    name: theme.name,
+    displayName: theme.displayName,
+    colors: theme.colors,
+    ...(theme.fontFamily !== undefined && { fontFamily: theme.fontFamily }),
+    ...(theme.letterSpacing !== undefined && { letterSpacing: theme.letterSpacing }),
+    ...(theme.textShadow !== undefined && { textShadow: theme.textShadow }),
+  }));

package/src/features/settings/utils/getBrowserTimezone.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { getBrowserTimezone } from './getBrowserTimezone';
+
+describe('getBrowserTimezone', () => {
+  it('returns a non-empty timezone string', () => {
+    const timezone = getBrowserTimezone();
+
+    expect(typeof timezone).toBe('string');
+    expect(timezone.length).toBeGreaterThan(0);
+  });
+});

package/src/features/settings/utils/getBrowserTimezone.ts

@@ -0,0 +1,7 @@
+// Get browser's timezone as default
+export const getBrowserTimezone = (): string => {
+  if (typeof window !== 'undefined' && Intl) {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  }
+  return 'UTC';
+};

package/src/features/settings/utils/getPreferenceSnapshot.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import type { Settings } from '@shellui/sdk';
+import { getPreferenceSnapshot } from './getPreferenceSnapshot';
+
+describe('getPreferenceSnapshot', () => {
+  it('returns explicit preferences from settings', () => {
+    const settings = {
+      appearance: { name: 'blue', colorScheme: 'dark' },
+      language: { code: 'fr' },
+      region: { timezone: 'Europe/Paris' },
+    } as Settings;
+
+    expect(getPreferenceSnapshot(settings)).toEqual({
+      themeName: 'blue',
+      language: 'fr',
+      region: 'Europe/Paris',
+      colorScheme: 'dark',
+    });
+  });
+
+  it('falls back to default values when settings fields are missing', () => {
+    const settings = {
+      appearance: { name: '', colorScheme: 'system' },
+      language: { code: 'en' },
+      region: { timezone: '' },
+    } as Settings;
+
+    const snapshot = getPreferenceSnapshot(settings);
+    expect(snapshot.themeName).toBe('default');
+    expect(snapshot.language).toBe('en');
+    expect(snapshot.colorScheme).toBe('system');
+    expect(typeof snapshot.region).toBe('string');
+    expect(snapshot.region?.length).toBeGreaterThan(0);
+  });
+});

package/src/features/settings/utils/getPreferenceSnapshot.ts

@@ -0,0 +1,10 @@
+import type { Settings } from '@shellui/sdk';
+import { getBrowserTimezone } from './getBrowserTimezone';
+import type { AppPreferences } from './mergePreferencesIntoSettings';
+
+export const getPreferenceSnapshot = (settings: Settings): AppPreferences => ({
+  themeName: settings.appearance?.name || 'default',
+  language: settings.language?.code || 'en',
+  region: settings.region?.timezone || getBrowserTimezone(),
+  colorScheme: settings.appearance?.colorScheme || 'system',
+});

package/src/features/settings/utils/getResolvedAppearanceForSettings.spec.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Settings } from '@shellui/sdk';
+import type { ShellUIConfig, ThemeDefinition } from '../../config/types';
+import { getResolvedAppearanceForSettings } from './getResolvedAppearanceForSettings';
+
+describe('getResolvedAppearanceForSettings', () => {
+  it('resolves and returns full appearance with registered theme data', () => {
+    vi.stubGlobal('window', {
+      location: { origin: 'https://shellui.dev' },
+      matchMedia: () => ({ matches: true }),
+    });
+
+    const customTheme: ThemeDefinition = {
+      name: 'custom-theme',
+      displayName: 'Custom Theme',
+      colors: {
+        light: {
+          background: '#fff',
+          foreground: '#000',
+          card: '#fff',
+          cardForeground: '#000',
+          popover: '#fff',
+          popoverForeground: '#000',
+          primary: '#000',
+          primaryForeground: '#fff',
+          secondary: '#eee',
+          secondaryForeground: '#000',
+          muted: '#eee',
+          mutedForeground: '#333',
+          accent: '#eee',
+          accentForeground: '#000',
+          destructive: '#f00',
+          destructiveForeground: '#fff',
+          border: '#ccc',
+          input: '#ccc',
+          ring: '#000',
+          radius: '0.5rem',
+          sidebarBackground: '#fff',
+          sidebarForeground: '#000',
+          sidebarPrimary: '#000',
+          sidebarPrimaryForeground: '#fff',
+          sidebarAccent: '#eee',
+          sidebarAccentForeground: '#000',
+          sidebarBorder: '#ccc',
+          sidebarRing: '#000',
+        },
+        dark: {
+          background: '#000',
+          foreground: '#fff',
+          card: '#000',
+          cardForeground: '#fff',
+          popover: '#000',
+          popoverForeground: '#fff',
+          primary: '#fff',
+          primaryForeground: '#000',
+          secondary: '#111',
+          secondaryForeground: '#fff',
+          muted: '#111',
+          mutedForeground: '#ddd',
+          accent: '#111',
+          accentForeground: '#fff',
+          destructive: '#900',
+          destructiveForeground: '#fff',
+          border: '#333',
+          input: '#333',
+          ring: '#fff',
+          radius: '0.5rem',
+          sidebarBackground: '#000',
+          sidebarForeground: '#fff',
+          sidebarPrimary: '#fff',
+          sidebarPrimaryForeground: '#000',
+          sidebarAccent: '#111',
+          sidebarAccentForeground: '#fff',
+          sidebarBorder: '#333',
+          sidebarRing: '#fff',
+        },
+      },
+      fontFiles: ['fonts/custom.woff2'],
+      fontFamily: 'Inter',
+    };
+
+    const settings = {
+      appearance: { name: 'custom-theme', colorScheme: 'system' },
+    } as Settings;
+
+    const config = {
+      themes: [customTheme],
+    } as ShellUIConfig;
+
+    const appearance = getResolvedAppearanceForSettings(settings, config);
+
+    expect(appearance?.name).toBe('custom-theme');
+    expect(appearance?.mode).toBe('dark');
+    expect(appearance?.fontFamily).toBe('Inter');
+    expect(appearance?.fontFiles).toEqual(['https://shellui.dev/fonts/custom.woff2']);
+  });
+});

package/src/features/settings/utils/getResolvedAppearanceForSettings.ts

@@ -0,0 +1,48 @@
+import type { Appearance, Settings } from '@shellui/sdk';
+import { getTheme, registerTheme } from '../../theme/themes';
+import type { ShellUIConfig } from '../../config/types';
+import { resolveColorMode } from './resolveColorMode';
+import { toAbsoluteFontUrls } from './toAbsoluteFontUrls';
+
+/**
+ * Build the full appearance object for settings propagation so apps receive all theme
+ * variable values and can style without knowing the theme name.
+ */
+export const getResolvedAppearanceForSettings = (
+  settings: Settings,
+  config: ShellUIConfig | undefined,
+): Appearance | undefined => {
+  if (typeof window === 'undefined') return undefined;
+
+  config?.themes?.forEach(registerTheme);
+  const themeName = settings.appearance?.name || config?.defaultTheme || 'default';
+  const themeDef = getTheme(themeName) || getTheme('default');
+  if (!themeDef) return undefined;
+
+  const colorScheme = settings.appearance?.colorScheme ?? 'system';
+  const mode = resolveColorMode(colorScheme);
+
+  return {
+    name: themeDef.name,
+    displayName: themeDef.displayName,
+    mode,
+    colorScheme,
+    colors: themeDef.colors,
+    ...(themeDef.fontFamily !== undefined && { fontFamily: themeDef.fontFamily }),
+    ...(themeDef.bodyFontFamily !== undefined && {
+      bodyFontFamily: themeDef.bodyFontFamily,
+    }),
+    ...(themeDef.headingFontFamily !== undefined && {
+      headingFontFamily: themeDef.headingFontFamily,
+    }),
+    ...(themeDef.letterSpacing !== undefined && {
+      letterSpacing: themeDef.letterSpacing,
+    }),
+    ...(themeDef.textShadow !== undefined && { textShadow: themeDef.textShadow }),
+    ...(themeDef.lineHeight !== undefined && { lineHeight: themeDef.lineHeight }),
+    ...(themeDef.fontFiles !== undefined &&
+      themeDef.fontFiles.length > 0 && {
+        fontFiles: toAbsoluteFontUrls(themeDef.fontFiles),
+      }),
+  };
+};

package/src/features/settings/utils/index.ts

@@ -0,0 +1,12 @@
+export { buildSettingsForPropagation } from './buildSettingsForPropagation';
+export { flattenNavigationItems } from './flattenNavigationItems';
+export { getAvailableThemesForSettings } from './getAvailableThemesForSettings';
+export { getBrowserTimezone } from './getBrowserTimezone';
+export { getPreferenceSnapshot } from './getPreferenceSnapshot';
+export { getResolvedAppearanceForSettings } from './getResolvedAppearanceForSettings';
+export { isSameUser } from './isSameUser';
+export { mergePreferencesIntoSettings, type AppPreferences } from './mergePreferencesIntoSettings';
+export { resolveColorMode } from './resolveColorMode';
+export { resolveLabel } from './resolveLabel';
+export { toAbsoluteFontUrls } from './toAbsoluteFontUrls';
+export { toSettingsUser } from './toSettingsUser';

package/src/features/settings/utils/isSameUser.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { isSameUser } from './isSameUser';
+
+describe('isSameUser', () => {
+  it('returns true when both users are null', () => {
+    expect(isSameUser(null, null)).toBe(true);
+  });
+
+  it('returns false when one user is missing', () => {
+    expect(
+      isSameUser(
+        {
+          id: 'u1',
+          email: 'test@example.com',
+          name: 'Test',
+          profilePicture: null,
+          authProvider: 'github',
+        },
+        null,
+      ),
+    ).toBe(false);
+  });
+
+  it('returns true when all user fields are identical', () => {
+    const user = {
+      id: 'u1',
+      email: 'test@example.com',
+      name: 'Test',
+      profilePicture: null,
+      authProvider: 'github',
+    };
+
+    expect(isSameUser(user, { ...user })).toBe(true);
+  });
+});

package/src/features/settings/utils/isSameUser.ts

@@ -0,0 +1,17 @@
+import type { Settings } from '@shellui/sdk';
+
+const groupsFingerprint = (g: Settings['user']): string => [...(g?.groups ?? [])].sort().join('\0');
+
+export const isSameUser = (a: Settings['user'], b: Settings['user']) => {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+
+  return (
+    a.id === b.id &&
+    a.email === b.email &&
+    a.name === b.name &&
+    a.profilePicture === b.profilePicture &&
+    a.authProvider === b.authProvider &&
+    groupsFingerprint(a) === groupsFingerprint(b)
+  );
+};

package/src/features/settings/utils/mergePreferencesIntoSettings.spec.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import type { Settings } from '@shellui/sdk';
+import { mergePreferencesIntoSettings } from './mergePreferencesIntoSettings';
+
+const baseSettings: Settings = {
+  developerFeatures: { enabled: false },
+  errorReporting: { enabled: true },
+  logging: { namespaces: { shellsdk: false, shellcore: false } },
+  appearance: {
+    name: 'default',
+    displayName: 'Default',
+    mode: 'light',
+    colorScheme: 'system',
+    colors: {
+      light: {
+        background: '#fff',
+        foreground: '#000',
+        card: '#fff',
+        cardForeground: '#000',
+        popover: '#fff',
+        popoverForeground: '#000',
+        primary: '#000',
+        primaryForeground: '#fff',
+        secondary: '#eee',
+        secondaryForeground: '#000',
+        muted: '#eee',
+        mutedForeground: '#333',
+        accent: '#eee',
+        accentForeground: '#000',
+        destructive: '#f00',
+        destructiveForeground: '#fff',
+        border: '#ccc',
+        input: '#ccc',
+        ring: '#000',
+        radius: '0.5rem',
+        sidebarBackground: '#fff',
+        sidebarForeground: '#000',
+        sidebarPrimary: '#000',
+        sidebarPrimaryForeground: '#fff',
+        sidebarAccent: '#eee',
+        sidebarAccentForeground: '#000',
+        sidebarBorder: '#ccc',
+        sidebarRing: '#000',
+      },
+      dark: {
+        background: '#000',
+        foreground: '#fff',
+        card: '#000',
+        cardForeground: '#fff',
+        popover: '#000',
+        popoverForeground: '#fff',
+        primary: '#fff',
+        primaryForeground: '#000',
+        secondary: '#111',
+        secondaryForeground: '#fff',
+        muted: '#111',
+        mutedForeground: '#ddd',
+        accent: '#111',
+        accentForeground: '#fff',
+        destructive: '#900',
+        destructiveForeground: '#fff',
+        border: '#333',
+        input: '#333',
+        ring: '#fff',
+        radius: '0.5rem',
+        sidebarBackground: '#000',
+        sidebarForeground: '#fff',
+        sidebarPrimary: '#fff',
+        sidebarPrimaryForeground: '#000',
+        sidebarAccent: '#111',
+        sidebarAccentForeground: '#fff',
+        sidebarBorder: '#333',
+        sidebarRing: '#fff',
+      },
+    },
+  },
+  language: { code: 'en' },
+  region: { timezone: 'UTC' },
+  cookieConsent: { acceptedHosts: [], consentedCookieHosts: [] },
+  serviceWorker: { enabled: true },
+  user: null,
+};
+
+describe('mergePreferencesIntoSettings', () => {
+  it('applies valid preference values', () => {
+    const result = mergePreferencesIntoSettings(baseSettings, {
+      themeName: 'blue',
+      language: 'fr',
+      region: 'Europe/Paris',
+      colorScheme: 'dark',
+    });
+
+    expect(result.appearance.name).toBe('blue');
+    expect(result.appearance.colorScheme).toBe('dark');
+    expect(result.language.code).toBe('fr');
+    expect(result.region.timezone).toBe('Europe/Paris');
+  });
+
+  it('keeps current language and color scheme when incoming values are invalid', () => {
+    const result = mergePreferencesIntoSettings(baseSettings, {
+      language: 'es',
+      colorScheme: undefined,
+    });
+
+    expect(result.language.code).toBe('en');
+    expect(result.appearance.colorScheme).toBe('system');
+  });
+});