@ankhorage/zora 6.0.0 → 8.0.0

package/src/features/splash-screen/adapters/inbound/SplashScreen.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+
+import { Center } from '../../../../foundation';
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { SplashScreenLogoShape, SplashScreenProps } from '../../../../types/splash-screen';
+import { Box, Stack } from '../../../layout/public';
+import { Heading } from '../../../typography/public';
+import { Text } from '../../../typography/public';
+/***
+ * Branded launch/loading surface for previews, web fallbacks, and app bootstrap states.
+ *
+ * `SplashScreen` is a React-rendered component. It intentionally does not manage
+ * Expo's native splash screen lifecycle or replace generated `expo-splash-screen`
+ * configuration.
+ */
+export const SplashScreen = withZoraThemeScope(SplashScreenInner);
+
+interface PlaceholderLogoProps {
+  label: string;
+  shape: SplashScreenLogoShape;
+  size: number;
+}
+
+function resolveLogoRadius(shape: SplashScreenLogoShape): number {
+  switch (shape) {
+    case 'circle':
+      return 9999;
+    case 'square':
+      return 0;
+    case 'rounded':
+    default:
+      return 28;
+  }
+}
+
+function PlaceholderLogo({ label, shape, size }: PlaceholderLogoProps) {
+  const { theme } = useZoraTheme();
+  const radius = resolveLogoRadius(shape);
+
+  return (
+    <Center
+      accessibilityLabel={label}
+      bg={theme.semantics.action.primary.base}
+      height={size}
+      width={size}
+      style={{ borderRadius: radius }}
+    >
+      <Text emphasis="inverse" variant="eyebrow" weight="bold">
+        {label.slice(0, 2).toUpperCase()}
+      </Text>
+    </Center>
+  );
+}
+
+function SplashScreenInner({
+  themeId: _themeId,
+  mode: _mode,
+  logo,
+  title,
+  subtitle,
+  children,
+  minHeight = '100%',
+  backgroundColor,
+  logoSize = 96,
+  logoLabel = 'ZORA',
+  logoShape = 'rounded',
+  testID,
+}: SplashScreenProps) {
+  const { theme } = useZoraTheme();
+  const background = backgroundColor ?? theme.semantics.neutral.surface;
+  const renderedLogo = logo ?? (
+    <PlaceholderLogo label={logoLabel} shape={logoShape} size={logoSize} />
+  );
+
+  return (
+    <Center bg={background} minHeight={minHeight} p="xl" testID={testID} width="100%">
+      <Stack align="center" gap="l" style={{ maxWidth: 360 }}>
+        {renderedLogo}
+        {title || subtitle ? (
+          <Stack align="center" gap="xs">
+            {title ? (
+              <Heading align="center" level={1} size="h1">
+                {title}
+              </Heading>
+            ) : null}
+            {subtitle ? (
+              <Text align="center" emphasis="muted" variant="bodySmall">
+                {subtitle}
+              </Text>
+            ) : null}
+          </Stack>
+        ) : null}
+        {children ? <Box width="100%">{children}</Box> : null}
+      </Stack>
+    </Center>
+  );
+}

package/src/features/splash-screen/public.ts

@@ -0,0 +1,2 @@
+export type { SplashScreenLogoShape, SplashScreenProps } from '../../types/splash-screen';
+export { SplashScreen } from './adapters/inbound/SplashScreen';

package/src/features/splash-screen/splashScreenMeta.ts

@@ -0,0 +1,41 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const splashScreenMeta = {
+  name: 'SplashScreen',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  description: 'App content splash presentation; does not control the native launch screen.',
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+    },
+    subtitle: {
+      type: 'string',
+      category: 'Content',
+    },
+    minHeight: {
+      type: 'number',
+      category: 'Layout',
+    },
+    backgroundColor: {
+      type: 'color',
+      category: 'Style',
+    },
+    logoSize: {
+      type: 'number',
+      category: 'Layout',
+    },
+    logoLabel: {
+      type: 'string',
+      category: 'Accessibility',
+    },
+    logoShape: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['circle', 'square', 'rounded'],
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/surface/adapters/inbound/Surface.tsx

@@ -0,0 +1,18 @@
+import { Surface as SurfaceSurface } from '@ankhorage/surface';
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { SurfaceProps } from '../../../../types/surface';
+
+/*** Adapts the themed Surface Surface primitive to ZORA scope and interaction props. */
+export const Surface = withZoraThemeScope(SurfaceInner);
+
+/*** Forwards presentation props to the published Surface boundary. */
+function SurfaceInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  ...props
+}: SurfaceProps) {
+  return <SurfaceSurface {...props} />;
+}

package/src/features/surface/public.ts

@@ -0,0 +1,2 @@
+export type { SurfaceProps, SurfaceVariant } from '../../types/surface';
+export { Surface } from './adapters/inbound/Surface';

package/src/features/surface/surfaceMeta.ts

@@ -0,0 +1,14 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { LAYOUT_PROPS } from '../layout/constants';
+
+export const surfaceMeta = {
+  name: 'Surface',
+  category: 'foundation',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  props: {
+    ...LAYOUT_PROPS,
+    variant: { type: 'enum', category: 'Style', enum: ['default', 'subtle', 'raised', 'outline'] },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/adapters/inbound/Heading.tsx

@@ -0,0 +1,114 @@
+import { resolveResponsive, useResponsiveRuntime } from '@ankhorage/surface';
+import React from 'react';
+import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../../../theme/useZoraThemeRecipe';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { HeadingProps } from '../../../../types/heading';
+import { resolveHeadingRecipe } from '../../utils/resolveHeadingRecipe';
+import { resolveHeadingSizeFromLevel } from '../../utils/resolveHeadingSizeFromLevel';
+import { resolveHeadingThemeRecipe } from '../../utils/resolveHeadingThemeRecipe';
+/***
+ * Structured title primitive for accessible page, section, and card headings.
+ *
+ * `Heading` gives consumers a ZORA-owned title API with semantic levels,
+ * responsive sizes, and theme-aware emphasis while preserving header semantics.
+ *
+ * @example Section title
+ * ```tsx
+ * <Heading level={2} size="xl">Account settings</Heading>
+ * ```
+ */
+export const Heading = withZoraThemeScope(HeadingInner);
+
+const headingLayoutStyle: TextStyle = {
+  flexShrink: 1,
+  maxWidth: '100%',
+  minWidth: 0,
+  ...(Platform.OS === 'web'
+    ? {
+        overflowWrap: 'break-word',
+        whiteSpace: 'normal',
+        wordBreak: 'normal',
+      }
+    : null),
+};
+
+function resolveHeadingContent({
+  children,
+  text,
+  i18nKey,
+}: Pick<HeadingProps, 'children' | 'text' | 'i18nKey'>) {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
+  return i18nKey;
+}
+
+function HeadingInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  text,
+  i18nKey,
+  level = 2,
+  size,
+  color,
+  emphasis,
+  align,
+  weight,
+  italic,
+  numberOfLines,
+  ellipsizeMode,
+  selectable,
+  style,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityRole,
+  nativeID,
+  testID,
+  interactionPolicy: _interactionPolicy,
+}: HeadingProps) {
+  const { theme } = useZoraTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveHeadingThemeRecipe(useZoraThemeRecipe('Heading'));
+  const content = resolveHeadingContent({ children, text, i18nKey });
+  const resolvedSize =
+    resolveResponsive(size ?? themeRecipe.size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
+  const resolvedColor = resolveResponsive(color ?? themeRecipe.color, breakpoint);
+  const resolvedEmphasis =
+    resolveResponsive(emphasis ?? themeRecipe.emphasis, breakpoint) ?? 'default';
+  const resolvedAlign = resolveResponsive(align ?? themeRecipe.align, breakpoint);
+  const resolvedWeight = resolveResponsive(weight ?? themeRecipe.weight, breakpoint);
+
+  if (content === null) return null;
+
+  return (
+    <ReactNativeText
+      accessibilityHint={accessibilityHint}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole={accessibilityRole ?? 'header'}
+      ellipsizeMode={ellipsizeMode}
+      nativeID={nativeID}
+      numberOfLines={numberOfLines}
+      selectable={selectable}
+      testID={testID}
+      style={[
+        headingLayoutStyle,
+        resolveHeadingRecipe(theme, {
+          align: resolvedAlign,
+          italic: italic ?? themeRecipe.italic ?? false,
+          level,
+          size: resolvedSize,
+          color: resolvedColor,
+          emphasis: resolvedEmphasis,
+          weight: resolvedWeight,
+        }),
+        style,
+      ]}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}

package/src/features/typography/adapters/inbound/Text.tsx

@@ -0,0 +1,110 @@
+import { resolveResponsive, useResponsiveRuntime } from '@ankhorage/surface';
+import React from 'react';
+import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../../../theme/useZoraThemeRecipe';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { TextProps } from '../../../../types/text';
+import { resolveTextStyle } from '../../utils/resolveTextStyle';
+import { resolveTextThemeRecipe } from '../../utils/resolveTextThemeRecipe';
+/***
+ * Structured copy primitive for theme-aware app text.
+ *
+ * `Text` owns normal body, caption, label, code, and supporting-copy variants so
+ * consumers do not need to import lower-level Surface typography directly.
+ *
+ * @example Muted supporting copy
+ * ```tsx
+ * <Text variant="bodySmall" emphasis="muted">Updated just now</Text>
+ * ```
+ */
+export const Text = withZoraThemeScope(TextInner);
+
+const textLayoutStyle: TextStyle = {
+  flexShrink: 1,
+  maxWidth: '100%',
+  minWidth: 0,
+  ...(Platform.OS === 'web'
+    ? {
+        overflowWrap: 'break-word',
+        whiteSpace: 'normal',
+        wordBreak: 'normal',
+      }
+    : null),
+};
+
+function resolveTextContent({
+  children,
+  text,
+  i18nKey,
+}: {
+  children: TextProps['children'];
+  text: TextProps['text'];
+  i18nKey: TextProps['i18nKey'];
+}): React.ReactNode {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
+  return i18nKey;
+}
+
+function TextInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  text,
+  i18nKey,
+  variant,
+  color,
+  emphasis,
+  align,
+  weight,
+  italic,
+  numberOfLines,
+  ellipsizeMode,
+  selectable,
+  style,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityRole,
+  accessibilityLiveRegion,
+  nativeID,
+  testID,
+  interactionPolicy: _interactionPolicy,
+}: TextProps) {
+  const { theme } = useZoraTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveTextThemeRecipe(useZoraThemeRecipe('Text'));
+  const content = resolveTextContent({ children, text, i18nKey });
+  const resolvedVariant = resolveResponsive(variant ?? themeRecipe.variant, breakpoint) ?? 'body';
+  const resolvedStyle = resolveTextStyle({
+    theme,
+    breakpoint,
+    variant: resolvedVariant,
+    color: color ?? themeRecipe.color,
+    emphasis: emphasis ?? themeRecipe.emphasis,
+    align: align ?? themeRecipe.align,
+    weight: weight ?? themeRecipe.weight,
+    italic: italic ?? themeRecipe.italic ?? false,
+  });
+
+  if (content === null || content === undefined) return null;
+
+  return (
+    <ReactNativeText
+      accessibilityHint={accessibilityHint}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityLiveRegion={accessibilityLiveRegion}
+      accessibilityRole={accessibilityRole}
+      ellipsizeMode={ellipsizeMode}
+      nativeID={nativeID}
+      numberOfLines={numberOfLines}
+      selectable={selectable}
+      testID={testID}
+      style={[textLayoutStyle, resolvedStyle, style]}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}

package/src/features/typography/headingMeta.ts

@@ -0,0 +1,82 @@
+import { COMPONENT_THEME_AUTHORING } from '../../constants';
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const headingMeta = {
+  name: 'Heading',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Heading', defaultProps: { text: 'Heading', level: 2 } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
+  props: {
+    text: {
+      type: 'string',
+      category: 'Content',
+      label: 'Text',
+      default: 'Heading',
+      authoring: { authority: 'instance' },
+    },
+    i18nKey: {
+      type: 'string',
+      category: 'Content',
+      label: 'i18n key',
+      authoring: { authority: 'instance' },
+    },
+    level: {
+      type: 'enum',
+      category: 'Semantics',
+      label: 'Level',
+      enum: [1, 2, 3, 4, 5, 6],
+      default: 2,
+      authoring: { authority: 'instance' },
+    },
+    size: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Size',
+      enum: ['display', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Color',
+      enum: ZORA_COLORS,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    emphasis: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Emphasis',
+      enum: ZORA_EMPHASES,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    align: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Align',
+      enum: ['auto', 'left', 'right', 'center', 'justify'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    weight: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Weight',
+      enum: ['regular', 'medium', 'semiBold', 'bold'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    italic: {
+      type: 'boolean',
+      category: 'Typography',
+      label: 'Italic',
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    numberOfLines: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Line clamp',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/public.ts

@@ -0,0 +1,19 @@
+export type {
+  HeadingAlign,
+  HeadingColor,
+  HeadingEmphasis,
+  HeadingLevel,
+  HeadingProps,
+  HeadingSize,
+  HeadingWeight,
+} from '../../types/heading';
+export type {
+  TextAlign,
+  TextColor,
+  TextEmphasis,
+  TextProps,
+  TextVariant,
+  TextWeight,
+} from '../../types/text';
+export { Heading } from './adapters/inbound/Heading';
+export { Text } from './adapters/inbound/Text';

package/src/features/typography/textMeta.ts

@@ -0,0 +1,74 @@
+import { COMPONENT_THEME_AUTHORING } from '../../constants';
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../internal/colorModel';
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const textMeta = {
+  name: 'Text',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Text', defaultProps: { text: 'Text' } },
+  i18n: { fields: [{ keyProp: 'i18nKey', defaultTextProp: 'text' }] },
+  props: {
+    text: {
+      type: 'string',
+      category: 'Content',
+      label: 'Text',
+      default: 'Text',
+      authoring: { authority: 'instance' },
+    },
+    i18nKey: {
+      type: 'string',
+      category: 'Content',
+      label: 'i18n key',
+      authoring: { authority: 'instance' },
+    },
+    variant: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Variant',
+      enum: ['body', 'lead', 'bodySmall', 'caption', 'label', 'eyebrow', 'code'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Color',
+      enum: ZORA_COLORS,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    emphasis: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Emphasis',
+      enum: ZORA_EMPHASES,
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    align: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Align',
+      enum: ['auto', 'left', 'right', 'center', 'justify'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    weight: {
+      type: 'enum',
+      category: 'Typography',
+      label: 'Weight',
+      enum: ['regular', 'medium', 'semiBold', 'bold'],
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    italic: {
+      type: 'boolean',
+      category: 'Typography',
+      label: 'Italic',
+      authoring: COMPONENT_THEME_AUTHORING,
+    },
+    numberOfLines: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Line clamp',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/utils/headingThemeRecipeMeta.ts

@@ -0,0 +1,33 @@
+import { ZORA_COLORS, ZORA_EMPHASES } from '../../../internal/colorModel';
+import type { ZoraThemeRecipeMeta } from '../../../metadata/themeRecipeTypes';
+
+export const headingThemeRecipeMeta = {
+  name: 'Heading',
+  kind: 'component',
+  description: 'Maps Heading presentation defaults without replacing semantic heading levels.',
+  fields: {
+    size: {
+      type: 'choice',
+      label: 'Size',
+      options: ['display', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+    },
+    color: { type: 'choice', label: 'Color', options: ZORA_COLORS },
+    emphasis: {
+      type: 'choice',
+      label: 'Emphasis',
+      options: ZORA_EMPHASES,
+      default: 'default',
+    },
+    align: {
+      type: 'choice',
+      label: 'Align',
+      options: ['auto', 'left', 'right', 'center', 'justify'],
+    },
+    weight: {
+      type: 'choice',
+      label: 'Weight',
+      options: ['regular', 'medium', 'semiBold', 'bold'],
+    },
+    italic: { type: 'boolean', label: 'Italic', default: false },
+  },
+} as const satisfies ZoraThemeRecipeMeta;