@laconius/ui 0.1.0

package/src/index.ts

@@ -0,0 +1,62 @@
+export {
+  defaultUiConfig,
+  type LaconiusUiComponent,
+  type LaconiusUiComponents,
+} from './config';
+
+export {
+  defineTheme,
+  extendTheme,
+  type ColorSchemePreference,
+  type Theme,
+  type ThemeColors,
+  type ThemeEntry,
+  type ThemeOverrides,
+  type TypographyRole,
+  type TypographyToken,
+} from './theme';
+
+export { kratos, kratosDark, kratosLight } from './kratos';
+
+export { useThemeStore, type ThemeState } from './store';
+
+export {
+  useStyles,
+  useTheme,
+  useThemeSwitcher,
+  useUiComponent,
+  type ThemeSwitcher,
+} from './hooks';
+
+export { defaultUiTranslations } from './translations';
+
+export { Text, type TextProps } from './text';
+export { Button, type ButtonProps, type ButtonVariant } from './button';
+export {
+  Media,
+  useMedia,
+  type MediaProps,
+  type UseMediaOptions,
+  type UseMediaResult,
+} from './media';
+export { Price, formatPrice, type PriceProps } from './price';
+export {
+  Divider,
+  EmptyState,
+  Spinner,
+  type DividerProps,
+  type EmptyStateProps,
+  type SpinnerProps,
+} from './feedback';
+export { QuantityStepper, type QuantityStepperProps } from './quantity-stepper';
+export {
+  useProductCard,
+  type ProductCardBadge,
+  type ProductCardView,
+} from './use-product-card';
+export { useGallery, type GalleryApi } from './use-gallery';
+export {
+  useQuantityStepper,
+  type QuantityStepperApi,
+  type QuantityStepperOptions,
+} from './use-quantity-stepper';

package/src/kratos.ts

@@ -0,0 +1,86 @@
+import { defineTheme, type Theme, type ThemeEntry } from './theme';
+
+const spacing = { xs: 4, sm: 8, md: 12, lg: 16, xl: 24, xxl: 32 };
+
+const typography = {
+  display: { fontSize: 32, lineHeight: 38, fontWeight: '700' },
+  heading: { fontSize: 24, lineHeight: 30, fontWeight: '700' },
+  subheading: { fontSize: 18, lineHeight: 24, fontWeight: '600' },
+  body: { fontSize: 16, lineHeight: 22, fontWeight: '400' },
+  label: { fontSize: 14, lineHeight: 18, fontWeight: '600', letterSpacing: 0.2 },
+  caption: { fontSize: 12, lineHeight: 16, fontWeight: '400' },
+} satisfies Theme['typography'];
+
+const radii = { sm: 4, md: 8, pill: 999 };
+
+const media = { aspectRatio: { product: 1, banner: 16 / 9, thumbnail: 1 } };
+
+function elevation(shadowColor: string, opacity: number): Theme['elevation'] {
+  return {
+    card: {
+      shadowColor,
+      shadowOffset: { width: 0, height: 1 },
+      shadowOpacity: opacity,
+      shadowRadius: 3,
+      elevation: 2,
+    },
+    modal: {
+      shadowColor,
+      shadowOffset: { width: 0, height: 6 },
+      shadowOpacity: opacity * 1.6,
+      shadowRadius: 16,
+      elevation: 12,
+    },
+  };
+}
+
+/**
+ * Every foreground/background pair below clears WCAG AA (4.5:1), verified by `kratos.test.ts`.
+ */
+export const kratosLight = defineTheme({
+  colors: {
+    background: '#FFFFFF',
+    surface: '#FFFFFF',
+    surfaceMuted: '#F4F4F5',
+    text: '#18181B',
+    textMuted: '#52525B',
+    textInverse: '#FFFFFF',
+    border: '#D4D4D8',
+    primary: '#1A56DB',
+    onPrimary: '#FFFFFF',
+    danger: '#B3261E',
+    success: '#146C43',
+  },
+  spacing,
+  typography,
+  radii,
+  elevation: elevation('#000000', 0.12),
+  media,
+});
+
+export const kratosDark = defineTheme({
+  colors: {
+    background: '#0B0B0F',
+    surface: '#17171B',
+    surfaceMuted: '#27272A',
+    text: '#F4F4F5',
+    textMuted: '#A1A1AA',
+    textInverse: '#18181B',
+    border: '#3F3F46',
+    primary: '#93B4FF',
+    onPrimary: '#0B0B0F',
+    danger: '#FF8A80',
+    success: '#6EE7A8',
+  },
+  spacing,
+  typography,
+  radii,
+  elevation: elevation('#000000', 0.5),
+  media,
+});
+
+export const kratos: ThemeEntry = {
+  name: 'Kratos',
+  light: kratosLight,
+  dark: kratosDark,
+};

package/src/media.tsx

@@ -0,0 +1,96 @@
+import {
+  getMediaBaseUrl,
+  resolveMediaCandidates,
+  useLaconiusConfig,
+  type MediaContainer,
+  type MediaSource,
+} from '@laconius/core';
+import { Image, type ImageProps } from 'expo-image';
+import { useMemo } from 'react';
+import type { ImageStyle, StyleProp } from 'react-native';
+
+import { useTheme } from './hooks';
+import type { Theme } from './theme';
+
+export type UseMediaOptions = {
+  /** Caps the candidate set. It does not select one asset. */
+  role?: string;
+  /** Explicit cap, overriding the one the role implies. */
+  maxFormat?: string;
+};
+
+export type UseMediaResult = {
+  /** Every format the container carries, widths attached, ascending. */
+  sources: MediaSource[];
+  altText?: string;
+};
+
+/**
+ * `expo-image` implements srcset semantics against the measured container, so Laconius hands it
+ * the whole candidate set and never picks a format for a device class.
+ */
+export function useMedia(
+  media: MediaContainer,
+  options: UseMediaOptions = {},
+): UseMediaResult {
+  const config = useLaconiusConfig();
+  const { role, maxFormat } = options;
+  return useMemo(
+    () => ({
+      sources: resolveMediaCandidates(media, {
+        baseUrl: getMediaBaseUrl(config),
+        role,
+        maxFormat,
+        formats: config.ui?.media?.formats,
+        roles: config.ui?.media?.roles,
+      }),
+      altText: (media as { altText?: string } | undefined)?.altText,
+    }),
+    [config, media, role, maxFormat],
+  );
+}
+
+export type MediaProps = Omit<ImageProps, 'source' | 'style'> & {
+  media: MediaContainer;
+  /**
+   * The `useMedia` role. Named `mediaRole` because React Native's own `role` (the ARIA one)
+   * is already on every view prop type, and a primitive spreads the platform props.
+   */
+  mediaRole?: string;
+  /** Explicit cap, overriding the one the role implies. */
+  maxFormat?: string;
+  /** A theme aspect-ratio role, or a number. Unset leaves layout to the caller. */
+  aspectRatio?: keyof Theme['media']['aspectRatio'] | number;
+  /** Hides the image from screen readers, for decorative content. */
+  decorative?: boolean;
+  style?: StyleProp<ImageStyle>;
+};
+
+export function Media({
+  media,
+  mediaRole,
+  maxFormat,
+  aspectRatio,
+  decorative = false,
+  style,
+  ...rest
+}: MediaProps) {
+  const theme = useTheme();
+  const { sources, altText } = useMedia(media, { role: mediaRole, maxFormat });
+  const ratio =
+    typeof aspectRatio === 'string' ? theme.media.aspectRatio[aspectRatio] : aspectRatio;
+
+  return (
+    <Image
+      source={sources}
+      contentFit="contain"
+      accessible={!decorative}
+      accessibilityRole={decorative ? undefined : 'image'}
+      accessibilityLabel={decorative ? undefined : altText}
+      accessibilityElementsHidden={decorative}
+      importantForAccessibility={decorative ? 'no-hide-descendants' : 'auto'}
+      style={[ratio === undefined ? null : { aspectRatio: ratio }, style]}
+      {...rest}
+    />
+  );
+}

package/src/price.tsx

@@ -0,0 +1,30 @@
+import { useSiteContext, type Price as PriceModel } from '@laconius/core';
+
+import { Text, type TextProps } from './text';
+
+export type PriceProps = Omit<TextProps, 'children'> & {
+  price?: PriceModel;
+  /** Rendered when the price carries neither a formatted value nor a numeric one. */
+  fallback?: string;
+};
+
+/**
+ * OCC's `formattedValue` arrives in the request's language and currency, so it follows a
+ * language switch on its own. `Intl` is the fallback for the endpoints that omit it — Hermes
+ * ships it, so there is no dependency here.
+ */
+export function formatPrice(price: PriceModel | undefined, locale: string): string | undefined {
+  if (!price) return undefined;
+  if (price.formattedValue) return price.formattedValue;
+  if (price.value === undefined) return undefined;
+  if (!price.currencyIso) return String(price.value);
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: price.currencyIso,
+  }).format(price.value);
+}
+
+export function Price({ price, fallback = '', ...rest }: PriceProps) {
+  const { language } = useSiteContext();
+  return <Text {...rest}>{formatPrice(price, language ?? 'en') ?? fallback}</Text>;
+}

package/src/quantity-stepper.tsx

@@ -0,0 +1,70 @@
+import { useTranslation } from '@laconius/core';
+import { StyleSheet, View, type StyleProp, type TextStyle, type ViewStyle } from 'react-native';
+
+import { Button } from './button';
+import { useStyles, useUiComponent } from './hooks';
+import { useQuantityStepper, type QuantityStepperOptions } from './use-quantity-stepper';
+import { Text } from './text';
+import type { Theme } from './theme';
+
+export type QuantityStepperProps = QuantityStepperOptions & {
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  styles?: {
+    container?: StyleProp<ViewStyle>;
+    value?: StyleProp<TextStyle>;
+    button?: StyleProp<ViewStyle>;
+  };
+};
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    root: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: theme.spacing.sm,
+      alignSelf: 'flex-start',
+    },
+    button: { paddingHorizontal: theme.spacing.md, minWidth: 44 },
+    value: { minWidth: 32, textAlign: 'center' },
+  });
+
+export function QuantityStepper({
+  disabled = false,
+  style,
+  styles: parts,
+  ...options
+}: QuantityStepperProps) {
+  const t = useTranslation();
+  const styles = useStyles(createStyles);
+  const Label = useUiComponent('Text', Text);
+  const Step = useUiComponent('Button', Button);
+  const stepper = useQuantityStepper(options);
+
+  return (
+    <View style={[styles.root, parts?.container, style]}>
+      <Step
+        variant="secondary"
+        title="−"
+        accessibilityLabel={t('ui.quantity.decrease')}
+        disabled={disabled || !stepper.canDecrement}
+        onPress={stepper.decrement}
+        style={[styles.button, parts?.button]}
+      />
+      <Label
+        accessibilityLabel={`${t('ui.quantity.label')} ${stepper.value}`}
+        style={[styles.value, parts?.value]}
+      >
+        {stepper.value}
+      </Label>
+      <Step
+        variant="secondary"
+        title="+"
+        accessibilityLabel={t('ui.quantity.increase')}
+        disabled={disabled || !stepper.canIncrement}
+        onPress={stepper.increment}
+        style={[styles.button, parts?.button]}
+      />
+    </View>
+  );
+}

package/src/store.ts

@@ -0,0 +1,35 @@
+import AsyncStorage from 'expo-sqlite/kv-store';
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+
+import type { ColorSchemePreference } from './theme';
+
+export type ThemeState = {
+  /** Unset means "whatever `ui.defaultTheme` says". */
+  activeThemeId?: string;
+  /** Unset means "whatever `ui.colorScheme` says". */
+  colorScheme?: ColorSchemePreference;
+  setTheme: (themeId: string) => void;
+  setColorScheme: (scheme: ColorSchemePreference) => void;
+};
+
+/**
+ * The runtime half of Spartacus' two-layer theming. React Native has no build-time SCSS swap, so
+ * the choice is state, and it survives a restart like any other preference.
+ */
+export const useThemeStore = create<ThemeState>()(
+  persist(
+    (set) => ({
+      setTheme: (activeThemeId) => set({ activeThemeId }),
+      setColorScheme: (colorScheme) => set({ colorScheme }),
+    }),
+    {
+      name: 'laconius.theme',
+      storage: createJSONStorage(() => AsyncStorage),
+      partialize: (state) => ({
+        activeThemeId: state.activeThemeId,
+        colorScheme: state.colorScheme,
+      }),
+    },
+  ),
+);

package/src/text.tsx

@@ -0,0 +1,49 @@
+import { StyleSheet, Text as RNText, type TextProps as RNTextProps } from 'react-native';
+
+import { useStyles, useTheme } from './hooks';
+import type { Theme, TypographyRole } from './theme';
+
+/**
+ * Primitives extend the platform prop type and spread the rest: a closed prop set broke on the
+ * first `numberOfLines` written in an app file.
+ */
+export type TextProps = RNTextProps & {
+  variant?: TypographyRole;
+  muted?: boolean;
+  /** For text sitting on `colors.primary`. */
+  inverse?: boolean;
+  color?: string;
+};
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    display: { ...theme.typography.display, fontFamily: theme.fontFamily?.bold },
+    heading: { ...theme.typography.heading, fontFamily: theme.fontFamily?.bold },
+    subheading: {
+      ...theme.typography.subheading,
+      fontFamily: theme.fontFamily?.medium,
+    },
+    body: { ...theme.typography.body, fontFamily: theme.fontFamily?.regular },
+    label: { ...theme.typography.label, fontFamily: theme.fontFamily?.medium },
+    caption: { ...theme.typography.caption, fontFamily: theme.fontFamily?.regular },
+  });
+
+export function Text({
+  variant = 'body',
+  muted,
+  inverse,
+  color,
+  style,
+  ...rest
+}: TextProps) {
+  const theme = useTheme();
+  const styles = useStyles(createStyles);
+  const resolved =
+    color ??
+    (inverse
+      ? theme.colors.textInverse
+      : muted
+        ? theme.colors.textMuted
+        : theme.colors.text);
+  return <RNText style={[styles[variant], { color: resolved }, style]} {...rest} />;
+}

package/src/theme.ts

@@ -0,0 +1,90 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+export type ThemeColors = {
+  background: string;
+  surface: string;
+  surfaceMuted: string;
+  text: string;
+  textMuted: string;
+  textInverse: string;
+  border: string;
+  primary: string;
+  onPrimary: string;
+  danger: string;
+  success: string;
+};
+
+export type TypographyRole =
+  | 'display'
+  | 'heading'
+  | 'subheading'
+  | 'body'
+  | 'label'
+  | 'caption';
+
+export type TypographyToken = Pick<
+  TextStyle,
+  'fontSize' | 'lineHeight' | 'fontWeight' | 'letterSpacing'
+>;
+
+/** Roles only, no numeric palette: the brand already has one and remapping it is work nobody asked for. */
+export type Theme = {
+  colors: ThemeColors;
+  spacing: { xs: number; sm: number; md: number; lg: number; xl: number; xxl: number };
+  typography: Record<TypographyRole, TypographyToken>;
+  radii: { sm: number; md: number; pill: number };
+  /** Two levels. `shadow*` on iOS, `elevation` on Android; both are set on each. */
+  elevation: { card: ViewStyle; modal: ViewStyle };
+  media: { aspectRatio: { product: number; banner: number; thumbnail: number } };
+  fontFamily?: { regular: string; medium: string; bold: string };
+};
+
+/** One theme, two schemes. `dark` is optional and falls back to `light`. */
+export type ThemeEntry = { name: string; light: Theme; dark?: Theme };
+
+export type ColorSchemePreference = 'system' | 'light' | 'dark';
+
+/**
+ * A complete theme, inheriting nothing. The compiler enumerates what is missing, which is why
+ * this is a separate function rather than a flag on `extendTheme`.
+ */
+export function defineTheme(theme: Theme): Theme {
+  return theme;
+}
+
+/** Deep merge onto an existing theme. */
+export function extendTheme(base: Theme, overrides: ThemeOverrides): Theme {
+  return mergeTheme(base, overrides) as Theme;
+}
+
+export type ThemeOverrides = {
+  [K in keyof Theme]?: Theme[K] extends object
+    ? { [P in keyof Theme[K]]?: Partial<Theme[K][P]> | Theme[K][P] }
+    : Theme[K];
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+/**
+ * Core's `deepMerge` semantics, kept local so this module imports nothing from a React Native
+ * runtime — a theme is the one thing worth building and testing outside a device.
+ */
+function mergeTheme(base: unknown, override: unknown): unknown {
+  if (override === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+
+  const result: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(override)) {
+    const next = override[key];
+    if (next === undefined) continue;
+    result[key] = isPlainObject(result[key]) ? mergeTheme(result[key], next) : next;
+  }
+  return result;
+}

package/src/translations.ts

@@ -0,0 +1,12 @@
+/** English strings for the defaults in this package. Other languages are the app's. */
+export const defaultUiTranslations = {
+  en: {
+    ui: {
+      quantity: {
+        label: 'Quantity',
+        increase: 'Increase quantity',
+        decrease: 'Decrease quantity',
+      },
+    },
+  },
+};

package/src/use-gallery.ts

@@ -0,0 +1,35 @@
+import { getGalleryImages, type ImageGroup, type Images } from '@laconius/core';
+import { useCallback, useMemo, useState } from 'react';
+
+export type GalleryApi = {
+  /** One entry per slide, each a group keyed by format code. */
+  items: ImageGroup[];
+  index: number;
+  selected: ImageGroup | undefined;
+  select: (index: number) => void;
+  next: () => void;
+  previous: () => void;
+};
+
+/** The selected slide — the only state a gallery owns. Paging is the caller's layout decision. */
+export function useGallery(images: Images | undefined): GalleryApi {
+  const items = useMemo(() => getGalleryImages(images), [images]);
+  const [index, setIndex] = useState(0);
+
+  // A product switch shortens the list; clamping on read avoids an effect that fights the render.
+  const current = items.length === 0 ? 0 : Math.min(index, items.length - 1);
+
+  const select = useCallback(
+    (next: number) => setIndex(Math.max(0, next)),
+    [],
+  );
+
+  return {
+    items,
+    index: current,
+    selected: items[current],
+    select,
+    next: () => select(Math.min(current + 1, items.length - 1)),
+    previous: () => select(current - 1),
+  };
+}

package/src/use-product-card.ts

@@ -0,0 +1,47 @@
+import { getPrimaryImage, type MediaContainer, type Price, type Product } from '@laconius/core';
+import { useMemo } from 'react';
+
+/**
+ * Semantic, not a translation key: the key space belongs to `@laconius/product`, and this hook
+ * lives in the UI kit, which never reaches into a feature package's namespace.
+ */
+export type ProductCardBadge = 'outOfStock' | 'lowStock';
+
+export type ProductCardView = {
+  code?: string;
+  title: string;
+  price?: Price;
+  media: MediaContainer;
+  badge?: ProductCardBadge;
+  averageRating?: number;
+  numberOfReviews?: number;
+};
+
+function badgeFor(product: Product): ProductCardBadge | undefined {
+  const status = product.stock?.stockLevelStatus;
+  if (product.purchasable === false || status === 'outOfStock') return 'outOfStock';
+  if (status === 'lowStock') return 'lowStock';
+  return undefined;
+}
+
+/**
+ * Derivation only — no fetch, no navigation. A card is rendered by the row of a `FlatList`, so
+ * everything it needs comes off the product it was handed.
+ *
+ * `priceRange.minPrice` covers the multidimensional products whose `price` is absent, which is
+ * what the search endpoint returns for apparel.
+ */
+export function useProductCard(product: Product | undefined): ProductCardView {
+  return useMemo(
+    () => ({
+      code: product?.code,
+      title: product?.name ?? '',
+      price: product?.price ?? product?.priceRange?.minPrice,
+      media: getPrimaryImage(product?.images),
+      badge: product ? badgeFor(product) : undefined,
+      averageRating: product?.averageRating,
+      numberOfReviews: product?.numberOfReviews,
+    }),
+    [product],
+  );
+}

package/src/use-quantity-stepper.ts

@@ -0,0 +1,35 @@
+export type QuantityStepperOptions = {
+  value: number;
+  /** Defaults to 1: zero quantity is a removal, which is the cart's decision, not the stepper's. */
+  min?: number;
+  max?: number;
+  onChange: (value: number) => void;
+};
+
+export type QuantityStepperApi = {
+  value: number;
+  canIncrement: boolean;
+  canDecrement: boolean;
+  increment: () => void;
+  decrement: () => void;
+  setValue: (value: number) => void;
+};
+
+/** Clamping and the disabled edges — the only state a stepper owns. It does not know what a cart is. */
+export function useQuantityStepper({
+  value,
+  min = 1,
+  max,
+  onChange,
+}: QuantityStepperOptions): QuantityStepperApi {
+  const clamp = (next: number) =>
+    Math.min(Math.max(Math.round(next), min), max ?? Number.POSITIVE_INFINITY);
+  return {
+    value,
+    canIncrement: max === undefined || value < max,
+    canDecrement: value > min,
+    increment: () => onChange(clamp(value + 1)),
+    decrement: () => onChange(clamp(value - 1)),
+    setValue: (next: number) => onChange(clamp(next)),
+  };
+}