@ankhorage/zora 0.9.0 → 0.11.0

package/src/patterns/panel/Panel.tsx

@@ -1,8 +1,11 @@
 import React from 'react';
 
 import { Card } from '../../components/card';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PanelProps } from './types';
 
-export function Panel(props: PanelProps) {
+function PanelInner({ themeId: _themeId, mode: _mode, ...props }: PanelProps) {
   return <Card {...props} />;
 }
+
+export const Panel = withZoraThemeScope(PanelInner);

package/src/patterns/panel/types.ts

@@ -1,8 +1,9 @@
 import type React from 'react';
 
 import type { ZoraCardTone } from '../../internal/recipes';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
 
-export interface PanelProps {
+export interface PanelProps extends ZoraBaseProps {
   title?: React.ReactNode;
   description?: React.ReactNode;
   eyebrow?: React.ReactNode;
@@ -11,5 +12,4 @@ export interface PanelProps {
   children?: React.ReactNode;
   tone?: ZoraCardTone;
   compact?: boolean;
-  testID?: string;
 }

package/src/patterns/responsive-panel/ResponsivePanel.tsx

@@ -2,10 +2,13 @@ import React from 'react';
 
 import { Drawer } from '../../components/drawer';
 import { Modal } from '../../components/modal';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { Panel } from '../panel';
 import type { ResponsivePanelProps } from './types';
 
-export function ResponsivePanel({
+function ResponsivePanelInner({
+  themeId: _themeId,
+  mode: _mode,
   title,
   description,
   actions,
@@ -68,3 +71,5 @@ export function ResponsivePanel({
     </Panel>
   );
 }
+
+export const ResponsivePanel = withZoraThemeScope(ResponsivePanelInner);

package/src/patterns/responsive-panel/types.ts

@@ -4,7 +4,9 @@ export type ResponsivePanelSide = 'left' | 'right';
 export type ResponsivePanelDesktopMode = 'inline' | 'floating';
 export type ResponsivePanelMobileMode = 'drawer' | 'modal';
 
-export interface ResponsivePanelProps {
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface ResponsivePanelProps extends ZoraBaseProps {
   title?: React.ReactNode;
   description?: React.ReactNode;
   actions?: React.ReactNode;
@@ -16,5 +18,4 @@ export interface ResponsivePanelProps {
   desktopMode?: ResponsivePanelDesktopMode;
   mobileMode?: ResponsivePanelMobileMode;
   compact?: boolean;
-  testID?: string;
 }

package/src/patterns/section-header/SectionHeader.tsx

@@ -3,9 +3,12 @@ import React from 'react';
 
 import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SectionHeaderProps } from './types';
 
-export function SectionHeader({
+function SectionHeaderInner({
+  themeId: _themeId,
+  mode: _mode,
   title,
   description,
   eyebrow,
@@ -39,3 +42,5 @@ export function SectionHeader({
     </Stack>
   );
 }
+
+export const SectionHeader = withZoraThemeScope(SectionHeaderInner);

package/src/patterns/section-header/types.ts

@@ -1,9 +1,10 @@
 import type React from 'react';
 
-export interface SectionHeaderProps {
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface SectionHeaderProps extends ZoraBaseProps {
   title: React.ReactNode;
   description?: React.ReactNode;
   eyebrow?: React.ReactNode;
   actions?: React.ReactNode;
-  testID?: string;
 }

package/src/patterns/settings-row/SettingsRow.tsx

@@ -3,9 +3,12 @@ import React from 'react';
 
 import { Card } from '../../components/card';
 import { Text } from '../../components/text';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { SettingsRowProps } from './types';
 
-export function SettingsRow({
+function SettingsRowInner({
+  themeId: _themeId,
+  mode: _mode,
   title,
   description,
   meta,
@@ -39,3 +42,5 @@ export function SettingsRow({
     </Card>
   );
 }
+
+export const SettingsRow = withZoraThemeScope(SettingsRowInner);

package/src/patterns/settings-row/types.ts

@@ -1,11 +1,12 @@
 import type React from 'react';
 
-interface SettingsRowBaseProps {
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+interface SettingsRowBaseProps extends ZoraBaseProps {
   title: React.ReactNode;
   description?: React.ReactNode;
   meta?: React.ReactNode;
   disabled?: boolean;
-  testID?: string;
 }
 
 interface SettingsRowPressableProps {

package/src/patterns/switch-field/SwitchField.tsx

@@ -1,10 +1,13 @@
 import { Switch } from '@ankhorage/surface';
 import React from 'react';
 
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { SettingsRow } from '../settings-row';
 import type { SwitchFieldProps } from './types';
 
-export function SwitchField({
+function SwitchFieldInner({
+  themeId: _themeId,
+  mode: _mode,
   label,
   description,
   value,
@@ -22,3 +25,5 @@ export function SwitchField({
     />
   );
 }
+
+export const SwitchField = withZoraThemeScope(SwitchFieldInner);

package/src/patterns/switch-field/types.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from 'react';
 
-export interface SwitchFieldProps {
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface SwitchFieldProps extends ZoraBaseProps {
   label: ReactNode;
   description?: ReactNode;
   value: boolean;
   onValueChange: (value: boolean) => void;
   disabled?: boolean;
-  testID?: string;
 }

package/src/patterns/tile-grid/PaletteItem.tsx

@@ -1,12 +1,16 @@
-import { Box, useTheme } from '@ankhorage/surface';
+import { Box } from '@ankhorage/surface';
 import React from 'react';
 
 import { Card } from '../../components/card';
 import { Heading } from '../../components/heading';
 import { Text } from '../../components/text';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PaletteItemProps } from './types';
 
-export function PaletteItem({
+function PaletteItemInner({
+  themeId: _themeId,
+  mode: _mode,
   title,
   description,
   icon,
@@ -16,7 +20,7 @@ export function PaletteItem({
   onPress,
   testID,
 }: PaletteItemProps) {
-  const { theme } = useTheme();
+  const { theme } = useZoraTheme();
 
   return (
     <Card
@@ -49,3 +53,5 @@ export function PaletteItem({
     </Card>
   );
 }
+
+export const PaletteItem = withZoraThemeScope(PaletteItemInner);

package/src/patterns/tile-grid/TileGrid.tsx

@@ -1,9 +1,12 @@
 import { Box } from '@ankhorage/surface';
 import React from 'react';
 
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { TileGridProps } from './types';
 
-export function TileGrid({
+function TileGridInner({
+  themeId: _themeId,
+  mode: _mode,
   children,
   columns = 'responsive',
   compact = false,
@@ -42,3 +45,5 @@ export function TileGrid({
     </Box>
   );
 }
+
+export const TileGrid = withZoraThemeScope(TileGridInner);

package/src/patterns/tile-grid/types.ts

@@ -1,14 +1,15 @@
 import type { ButtonIconSpec } from '@ankhorage/surface';
 import type { ReactNode } from 'react';
 
-export interface TileGridProps {
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface TileGridProps extends ZoraBaseProps {
   children?: ReactNode;
   columns?: number | 'responsive';
   compact?: boolean;
-  testID?: string;
 }
 
-export interface PaletteItemProps {
+export interface PaletteItemProps extends ZoraBaseProps {
   title: ReactNode;
   description?: ReactNode;
   icon?: ButtonIconSpec;
@@ -16,5 +17,4 @@ export interface PaletteItemProps {
   selected?: boolean;
   disabled?: boolean;
   onPress?: () => void;
-  testID?: string;
 }

package/src/patterns/tree-view/TreeItem.tsx

@@ -2,10 +2,12 @@ import { Box, Stack } from '@ankhorage/surface';
 import React from 'react';
 
 import { IconButton } from '../../components/icon-button';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
 import { SettingsRow } from '../settings-row';
 import type { TreeItemNode, TreeItemRenderProps } from './types';
 
-interface TreeItemProps<TId extends string = string> {
+interface TreeItemProps<TId extends string = string> extends ZoraBaseProps {
   node: TreeItemNode<TId>;
   depth: number;
   selectedId?: TId;
@@ -15,7 +17,9 @@ interface TreeItemProps<TId extends string = string> {
   renderItem?: (props: TreeItemRenderProps<TId>) => React.ReactNode;
 }
 
-export function TreeItem<TId extends string = string>({
+function TreeItemInner<TId extends string = string>({
+  themeId: _themeId,
+  mode: _mode,
   node,
   depth,
   selectedId,
@@ -23,6 +27,7 @@ export function TreeItem<TId extends string = string>({
   onSelect,
   onToggleExpand,
   renderItem,
+  testID,
 }: TreeItemProps<TId>) {
   const hasChildren = node.children !== undefined && node.children.length > 0;
   const isExpanded = expandedIds.includes(node.id);
@@ -63,7 +68,7 @@ export function TreeItem<TId extends string = string>({
   };
 
   return (
-    <Box>
+    <Box testID={testID}>
       <Box style={{ paddingLeft: depth * 16 }}>{renderContent()}</Box>
       {hasChildren && isExpanded ? (
         <Box>
@@ -84,3 +89,5 @@ export function TreeItem<TId extends string = string>({
     </Box>
   );
 }
+
+export const TreeItem = withZoraThemeScope(TreeItemInner);

package/src/patterns/tree-view/TreeView.tsx

@@ -1,10 +1,13 @@
 import { Stack } from '@ankhorage/surface';
 import React from 'react';
 
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import { TreeItem } from './TreeItem';
 import type { TreeViewProps } from './types';
 
-export function TreeView<TId extends string = string>({
+function TreeViewInner<TId extends string = string>({
+  themeId: _themeId,
+  mode: _mode,
   nodes,
   selectedId,
   expandedIds: controlledExpandedIds,
@@ -48,3 +51,5 @@ export function TreeView<TId extends string = string>({
     </Stack>
   );
 }
+
+export const TreeView = withZoraThemeScope(TreeViewInner);

package/src/patterns/tree-view/types.ts

@@ -1,6 +1,8 @@
 import type { ButtonIconSpec } from '@ankhorage/surface';
 import type { ReactNode } from 'react';
 
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
 export interface TreeItemNode<TId extends string = string> {
   id: TId;
   label: ReactNode;
@@ -19,7 +21,7 @@ export interface TreeItemRenderProps<TId extends string = string> {
   hasChildren: boolean;
 }
 
-export interface TreeViewProps<TId extends string = string> {
+export interface TreeViewProps<TId extends string = string> extends ZoraBaseProps {
   nodes: readonly TreeItemNode<TId>[];
   selectedId?: TId;
   expandedIds?: readonly TId[];
@@ -27,5 +29,4 @@ export interface TreeViewProps<TId extends string = string> {
   onSelect?: (id: TId) => void;
   onExpandedChange?: (ids: readonly TId[]) => void;
   renderItem?: (props: TreeItemRenderProps<TId>) => ReactNode;
-  testID?: string;
 }

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);
+}