@ankhorage/zora 0.9.0 → 0.10.0

package/src/theme/ZoraBaseProps.ts

@@ -0,0 +1,20 @@
+import type { ZoraThemeId, ZoraThemeMode } from './types';
+
+export interface ZoraBaseProps {
+  /**
+   * Overrides the active ZORA theme for this component and its subtree.
+   * If omitted, the nearest parent theme is inherited.
+   *
+   * Plan 2: theme registries are not available yet. Only the inherited theme id
+   * is valid; unknown ids throw in dev/test and warn+fallback in production.
+   */
+  themeId?: ZoraThemeId;
+
+  /**
+   * Overrides the light/dark mode for this component and its subtree.
+   * If omitted, the nearest parent mode is inherited.
+   */
+  mode?: ZoraThemeMode;
+
+  testID?: string;
+}

package/src/theme/ZoraProvider.tsx

@@ -1,9 +1,10 @@
-import { ResponsiveProvider, ThemeProvider } from '@ankhorage/surface';
+import { ThemeProvider } from '@ankhorage/surface';
 import React from 'react';
 
 import { createZoraThemeConfig } from './createZoraThemeConfig';
 import type { ZoraTheme, ZoraThemeMode } from './types';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
+import { ZoraThemeRuntimeContext } from './ZoraThemeRuntimeContext';
 
 export interface ZoraProviderProps {
   children: React.ReactNode;
@@ -16,9 +17,13 @@ export function ZoraProvider({
   theme = zoraDefaultTheme,
   initialMode = 'light',
 }: ZoraProviderProps) {
+  const runtimeValue = React.useMemo(() => ({ sourceTheme: theme, themeId: theme.id }), [theme]);
+
   return (
-    <ThemeProvider initialConfig={createZoraThemeConfig(theme)} initialMode={initialMode}>
-      <ResponsiveProvider>{children}</ResponsiveProvider>
-    </ThemeProvider>
+    <ZoraThemeRuntimeContext.Provider value={runtimeValue}>
+      <ThemeProvider initialConfig={createZoraThemeConfig(theme)} initialMode={initialMode}>
+        {children}
+      </ThemeProvider>
+    </ZoraThemeRuntimeContext.Provider>
   );
 }

package/src/theme/ZoraThemeRuntimeContext.tsx

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+
+import type { ZoraTheme, ZoraThemeId } from './types';
+import { zoraDefaultTheme } from './zoraDefaultTheme';
+
+interface ZoraThemeRuntime {
+  sourceTheme: ZoraTheme;
+  themeId: ZoraThemeId;
+}
+
+export const ZoraThemeRuntimeContext = createContext<ZoraThemeRuntime>({
+  sourceTheme: zoraDefaultTheme,
+  themeId: zoraDefaultTheme.id,
+});
+
+export function useZoraThemeRuntime(): ZoraThemeRuntime {
+  return useContext(ZoraThemeRuntimeContext);
+}

package/src/theme/ZoraThemeScope.tsx

@@ -0,0 +1,74 @@
+import { createTheme, ThemeContext, useFontContext, useTheme } from '@ankhorage/surface';
+import React, { useMemo } from 'react';
+
+import { createZoraThemeConfig } from './createZoraThemeConfig';
+import { resolveZoraScopedThemeId } from './resolveZoraScopedThemeId';
+import type { ZoraThemeId, ZoraThemeMode } from './types';
+import { useZoraThemeRuntime, ZoraThemeRuntimeContext } from './ZoraThemeRuntimeContext';
+
+export interface ZoraThemeScopeProps {
+  children: React.ReactNode;
+  themeId?: ZoraThemeId;
+  mode?: ZoraThemeMode;
+}
+
+function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
+  const parentSurface = useTheme();
+  const parentRuntime = useZoraThemeRuntime();
+  const { activeFontId } = useFontContext();
+
+  const scopedThemeId = resolveZoraScopedThemeId({
+    desiredThemeId: themeId,
+    inheritedThemeId: parentRuntime.themeId,
+  });
+
+  const scopedMode = mode ?? parentSurface.mode;
+
+  // Plan 2: there is no multi-theme registry yet. Keep the active theme seed inherited.
+  const surfaceConfig = useMemo(
+    () => createZoraThemeConfig(parentRuntime.sourceTheme),
+    [parentRuntime.sourceTheme],
+  );
+
+  const scopedTheme = useMemo(
+    () => createTheme(surfaceConfig, scopedMode, activeFontId),
+    [surfaceConfig, scopedMode, activeFontId],
+  );
+
+  const scopedSurfaceValue = useMemo(
+    () => ({
+      theme: scopedTheme,
+      mode: scopedMode,
+      setMode: parentSurface.setMode,
+      setThemeConfig: parentSurface.setThemeConfig,
+      _hasProvider: true,
+    }),
+    [parentSurface.setMode, parentSurface.setThemeConfig, scopedMode, scopedTheme],
+  );
+
+  const scopedRuntimeValue = useMemo(
+    () => ({
+      sourceTheme: parentRuntime.sourceTheme,
+      themeId: scopedThemeId,
+    }),
+    [parentRuntime.sourceTheme, scopedThemeId],
+  );
+
+  return (
+    <ZoraThemeRuntimeContext.Provider value={scopedRuntimeValue}>
+      <ThemeContext.Provider value={scopedSurfaceValue}>{children}</ThemeContext.Provider>
+    </ZoraThemeRuntimeContext.Provider>
+  );
+}
+
+export function ZoraThemeScope({ children, themeId, mode }: ZoraThemeScopeProps) {
+  if (mode === undefined && themeId === undefined) {
+    return children;
+  }
+
+  return (
+    <ZoraThemeScopeInner mode={mode} themeId={themeId}>
+      {children}
+    </ZoraThemeScopeInner>
+  );
+}

package/src/theme/index.ts

@@ -9,6 +9,10 @@ export type {
   ZoraThemeMode,
 } from './types';
 export { useZoraTheme } from './useZoraTheme';
+export { withZoraThemeScope } from './withZoraThemeScope';
+export type { ZoraBaseProps } from './ZoraBaseProps';
 export { zoraDefaultTheme } from './zoraDefaultTheme';
 export type { ZoraProviderProps } from './ZoraProvider';
 export { ZoraProvider } from './ZoraProvider';
+export type { ZoraThemeScopeProps } from './ZoraThemeScope';
+export { ZoraThemeScope } from './ZoraThemeScope';

package/src/theme/resolveZoraScopedThemeId.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveZoraScopedThemeId } from './resolveZoraScopedThemeId';
+
+describe('resolveZoraScopedThemeId', () => {
+  it('inherits the theme id when omitted', () => {
+    expect(resolveZoraScopedThemeId({ desiredThemeId: undefined, inheritedThemeId: 'zora' })).toBe(
+      'zora',
+    );
+  });
+
+  it('accepts the inherited theme id when explicitly provided', () => {
+    expect(resolveZoraScopedThemeId({ desiredThemeId: 'zora', inheritedThemeId: 'zora' })).toBe(
+      'zora',
+    );
+  });
+
+  it('throws in non-production for unknown theme ids', () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'test';
+
+    expect(() =>
+      resolveZoraScopedThemeId({ desiredThemeId: 'studio', inheritedThemeId: 'zora' }),
+    ).toThrow(/Unknown ZORA theme id 'studio'/);
+
+    process.env.NODE_ENV = originalEnv;
+  });
+
+  it('warns and falls back in production for unknown theme ids', () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+    console.warn = (message: string) => {
+      warnings.push(message);
+    };
+
+    expect(resolveZoraScopedThemeId({ desiredThemeId: 'studio', inheritedThemeId: 'zora' })).toBe(
+      'zora',
+    );
+    expect(warnings.join('\n')).toMatch(/Unknown ZORA theme id 'studio'/);
+
+    console.warn = originalWarn;
+    process.env.NODE_ENV = originalEnv;
+  });
+});

package/src/theme/resolveZoraScopedThemeId.ts

@@ -0,0 +1,25 @@
+import type { ZoraThemeId } from './types';
+
+export function resolveZoraScopedThemeId({
+  desiredThemeId,
+  inheritedThemeId,
+}: {
+  desiredThemeId: ZoraThemeId | undefined;
+  inheritedThemeId: ZoraThemeId;
+}): ZoraThemeId {
+  if (desiredThemeId === undefined || desiredThemeId === inheritedThemeId) {
+    return inheritedThemeId;
+  }
+
+  const message = [
+    `Unknown ZORA theme id '${desiredThemeId}'.`,
+    'Theme registries are not available yet; register the theme before using themeId scopes.',
+  ].join(' ');
+
+  if (process.env.NODE_ENV === 'production') {
+    console.warn(message);
+    return inheritedThemeId;
+  }
+
+  throw new Error(message);
+}

package/src/theme/themeScopeStructure.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Replace themeScopeStructure.test.ts with real behavior tests once the ZORA component test strategy is decided.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'bun:test';
+
+const themeDir = import.meta.dir;
+
+const zoraProviderSource = readFileSync(join(themeDir, 'ZoraProvider.tsx'), 'utf8');
+const themeScopeSource = readFileSync(join(themeDir, 'ZoraThemeScope.tsx'), 'utf8');
+const hocSource = readFileSync(join(themeDir, 'withZoraThemeScope.tsx'), 'utf8');
+
+const textSource = readFileSync(join(themeDir, '..', 'components', 'text', 'Text.tsx'), 'utf8');
+const headingSource = readFileSync(
+  join(themeDir, '..', 'components', 'heading', 'Heading.tsx'),
+  'utf8',
+);
+const buttonSource = readFileSync(
+  join(themeDir, '..', 'components', 'button', 'Button.tsx'),
+  'utf8',
+);
+const iconSource = readFileSync(join(themeDir, '..', 'components', 'icon', 'Icon.tsx'), 'utf8');
+const iconButtonSource = readFileSync(
+  join(themeDir, '..', 'components', 'icon-button', 'IconButton.tsx'),
+  'utf8',
+);
+const cardSource = readFileSync(join(themeDir, '..', 'components', 'card', 'Card.tsx'), 'utf8');
+const panelSource = readFileSync(join(themeDir, '..', 'patterns', 'panel', 'Panel.tsx'), 'utf8');
+
+const textTypesSource = readFileSync(
+  join(themeDir, '..', 'components', 'text', 'types.ts'),
+  'utf8',
+);
+const headingTypesSource = readFileSync(
+  join(themeDir, '..', 'components', 'heading', 'types.ts'),
+  'utf8',
+);
+const panelTypesSource = readFileSync(
+  join(themeDir, '..', 'patterns', 'panel', 'types.ts'),
+  'utf8',
+);
+
+describe('theme scope structure', () => {
+  it('keeps ZoraProvider lightweight (no extra ResponsiveProvider nesting)', () => {
+    expect(zoraProviderSource).toMatch(/ThemeProvider/);
+    expect(zoraProviderSource).toMatch(/ZoraThemeRuntimeContext\.Provider/);
+    expect(zoraProviderSource).not.toMatch(/ResponsiveProvider/);
+  });
+
+  it('implements nested scopes without nesting Surface ThemeProvider', () => {
+    expect(themeScopeSource).toMatch(/ThemeContext\.Provider/);
+    expect(themeScopeSource).toMatch(/createTheme\(/);
+    expect(themeScopeSource).not.toMatch(/ThemeProvider/);
+  });
+
+  it('wraps components only when mode/themeId overrides are present', () => {
+    expect(hocSource).toMatch(/props\.mode === undefined/);
+    expect(hocSource).toMatch(/props\.themeId === undefined/);
+    expect(hocSource).toMatch(/<ZoraThemeScope/);
+  });
+
+  it('adopts the inner + HOC pattern for the first component set', () => {
+    expect(textSource).toMatch(/themeId: _themeId/);
+    expect(textSource).toMatch(/mode: _mode/);
+    expect(textSource).toMatch(/export const Text = withZoraThemeScope/);
+
+    expect(headingSource).toMatch(/themeId: _themeId/);
+    expect(headingSource).toMatch(/mode: _mode/);
+    expect(headingSource).toMatch(/export const Heading = withZoraThemeScope/);
+
+    expect(buttonSource).toMatch(/themeId: _themeId/);
+    expect(buttonSource).toMatch(/mode: _mode/);
+    expect(buttonSource).toMatch(/export const Button = withZoraThemeScope/);
+
+    expect(iconSource).toMatch(/themeId: _themeId/);
+    expect(iconSource).toMatch(/mode: _mode/);
+    expect(iconSource).toMatch(/export const Icon = withZoraThemeScope/);
+
+    expect(iconButtonSource).toMatch(/themeId: _themeId/);
+    expect(iconButtonSource).toMatch(/mode: _mode/);
+    expect(iconButtonSource).toMatch(/export const IconButton = withZoraThemeScope/);
+
+    expect(cardSource).toMatch(/themeId: _themeId/);
+    expect(cardSource).toMatch(/mode: _mode/);
+    expect(cardSource).toMatch(/export const Card = withZoraThemeScope/);
+
+    expect(panelSource).toMatch(/themeId: _themeId/);
+    expect(panelSource).toMatch(/mode: _mode/);
+    expect(panelSource).toMatch(/export const Panel = withZoraThemeScope/);
+  });
+
+  it('adds ZoraBaseProps to converted public prop types', () => {
+    expect(textTypesSource).toMatch(/export interface TextProps extends ZoraBaseProps/);
+    expect(headingTypesSource).toMatch(/export interface HeadingProps extends ZoraBaseProps/);
+    expect(panelTypesSource).toMatch(/export interface PanelProps extends ZoraBaseProps/);
+  });
+});

package/src/theme/withZoraThemeScope.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+
+import type { ZoraBaseProps } from './ZoraBaseProps';
+import { ZoraThemeScope } from './ZoraThemeScope';
+
+export function withZoraThemeScope<P extends ZoraBaseProps>(
+  Component: React.ComponentType<P>,
+): React.FC<P> {
+  const Wrapped: React.FC<P> = (props) => {
+    if (props.mode === undefined && props.themeId === undefined) {
+      return <Component {...props} />;
+    }
+
+    return (
+      <ZoraThemeScope mode={props.mode} themeId={props.themeId}>
+        <Component {...props} />
+      </ZoraThemeScope>
+    );
+  };
+
+  const name = Component.displayName ?? (Component.name || 'Component');
+  Wrapped.displayName = `withZoraThemeScope(${name})`;
+
+  return Wrapped;
+}