orn-ui 0.2.10 → 0.3.0

package/src/theme/createTheme.ts

@@ -26,7 +26,7 @@ function mergeDeep<T extends Record<string, any>>(base: T, patch?: Partial<T>):
 
 const capitalize = <T extends string>(name: T) => (name.charAt(0).toUpperCase() + name.slice(1)) as Capitalize<T>;
 
-/** Expande cada hex de `brand` a los cuatro roles del acento en un esquema. */
+/** Expands each `brand` hex into the accent's four roles in a scheme. */
 function brandColors(
   brand: ThemeOverrides['brand'],
   scheme: 'light' | 'dark',
@@ -49,12 +49,12 @@ function brandColors(
 }
 
 /**
- * Construye el par de themes light/dark que consume <UIProvider theme={...}>.
- * Nunca muta los defaults: cada llamada produce objetos nuevos, seguros de
- * compartir entre providers distintos (tests, multi-brand en el mismo árbol).
+ * Builds the light/dark theme pair consumed by <UIProvider theme={...}>.
+ * Never mutates the defaults: each call produces new objects, safe to share
+ * between different providers (tests, multi-brand in the same tree).
  *
- * `brand` se aplica antes que `colors`, así que un rol escrito a mano siempre
- * gana sobre el derivado.
+ * `brand` is applied before `colors`, so a hand-written role always wins
+ * over the derived one.
  */
 export function createTheme(overrides?: ThemeOverrides): ThemePair {
   const tokens = mergeDeep(defaultTokens, overrides?.tokens as any);

package/src/theme/index.ts

@@ -1,4 +1,4 @@
-export { spacing, radius, fontSize, fontWeight, lineHeight, duration, shadow, tokens } from './tokens';
+export { spacing, radius, fontSize, fontWeight, lineHeight, letterSpacing, duration, shadow, tokens } from './tokens';
 export type { Tokens } from './tokens';
 export { lightPalette, darkPalette } from './palettes';
 export type { ThemeColors } from './palettes';

package/src/theme/insets.ts

@@ -1,4 +1,4 @@
-/** Estructuralmente igual a EdgeInsets de react-native-safe-area-context, sin depender del paquete. */
+/** Structurally identical to react-native-safe-area-context's EdgeInsets, without depending on the package. */
 export interface EdgeInsets {
   top: number;
   right: number;

package/src/theme/labels.ts

@@ -8,12 +8,67 @@ export interface Labels {
   noResultsDescription: string;
   search: string;
   selectPlaceholder: string;
-  /** Nombres de los meses, de enero a diciembre. */
+  /** Month names, January to December. */
   months: string[];
-  /** Iniciales de los días, índice 0 = domingo (alinea con `Date.getDay()`). */
+  /** Weekday initials, index 0 = Sunday (matches `Date.getDay()`). */
   weekdaysShort: string[];
   selectDate: string;
   clear: string;
+  /** Eye button in Input with `isPassword`. */
+  showPassword: string;
+  hidePassword: string;
+  /** Appended to the accessible name of a `required` field (the asterisk is visual only). */
+  required: string;
+  /** Input validation: shown when a `required` field is empty. */
+  requiredError: string;
+  /** Input validation, `rules.minLength`. `{n}` is replaced by the limit. */
+  minLengthError: string;
+  /** Input validation, `rules.maxLength`. `{n}` is replaced by the limit. */
+  maxLengthError: string;
+  /** Input validation, `rules.pattern`. */
+  patternError: string;
+  /** Stepper: accessible name of the numeric field. */
+  quantity: string;
+  /** Stepper: "+" button. */
+  increment: string;
+  /** Stepper: "-" button. */
+  decrement: string;
+  /** Steps: accessible name of a step. `{n}`, `{total}` and `{label}` are replaced. */
+  stepOf: string;
+  /** Steps: state of a step already done. */
+  stepCompleted: string;
+  /** Steps: state of the step in progress. */
+  stepCurrent: string;
+  /** Steps: state of a step not reached yet. */
+  stepPending: string;
+  /** DatePicker: button to the previous month. */
+  previousMonth: string;
+  /** DatePicker: button to the next month. */
+  nextMonth: string;
+  /** ReorderableList: screen-reader action that moves a row one place up. */
+  moveUp: string;
+  /** ReorderableList: screen-reader action that moves a row one place down. */
+  moveDown: string;
+  /** SearchList: accessible name of the scan button. */
+  scan: string;
+  /** Slides: indicator name. `{n}` and `{total}` are replaced. */
+  slideOf: string;
+  /** Slides: button that pauses autoPlay. */
+  pauseSlides: string;
+  /** Slides: button that resumes autoPlay. */
+  resumeSlides: string;
+  /** ThemeToggle: segment that follows the system appearance. */
+  themeSystem: string;
+  /** ThemeToggle: light segment. */
+  themeLight: string;
+  /** ThemeToggle: dark segment. */
+  themeDark: string;
+  /** Wizard: button to the previous step. */
+  back: string;
+  /** Wizard: button to the next step. */
+  next: string;
+  /** Wizard: next button on the last step. */
+  finish: string;
 }
 
 export const defaultLabels: Labels = {
@@ -33,4 +88,32 @@ export const defaultLabels: Labels = {
   weekdaysShort: ['S', 'M', 'T', 'W', 'T', 'F', 'S'],
   selectDate: 'Select date',
   clear: 'Clear',
+  showPassword: 'Show password',
+  hidePassword: 'Hide password',
+  required: 'required',
+  requiredError: 'This field is required',
+  minLengthError: 'Enter at least {n} characters',
+  maxLengthError: 'Enter at most {n} characters',
+  patternError: 'Invalid format',
+  quantity: 'Quantity',
+  increment: 'Increment',
+  decrement: 'Decrement',
+  stepOf: 'Step {n} of {total}: {label}',
+  stepCompleted: 'completed',
+  stepCurrent: 'current',
+  stepPending: 'pending',
+  previousMonth: 'Previous month',
+  nextMonth: 'Next month',
+  moveUp: 'Move up',
+  moveDown: 'Move down',
+  scan: 'Scan',
+  slideOf: 'Slide {n} of {total}',
+  pauseSlides: 'Pause automatic slides',
+  resumeSlides: 'Resume automatic slides',
+  themeSystem: 'Auto',
+  themeLight: 'Light',
+  themeDark: 'Dark',
+  back: 'Back',
+  next: 'Next',
+  finish: 'Finish',
 };

package/src/theme/palettes.ts

@@ -1,21 +1,21 @@
 /**
- * Cada color es `string`, no un literal (`as const`): light y dark tienen
- * valores distintos para la misma clave, y createTheme() debe poder
- * aceptar cualquier hex/rgba en los overrides — literal typing lo impediría.
+ * Each color is a `string`, not a literal (`as const`): light and dark have
+ * different values for the same key, and createTheme() must be able to
+ * accept any hex/rgba in the overrides — literal typing would prevent it.
  *
- * Cada acento viene en cuatro roles, y no son intercambiables:
+ * Each accent comes in four roles, and they are not interchangeable:
  *
- *   `primary`      relleno sólido (fondo de botón, día seleccionado, FAB).
- *   `onPrimary`    texto/ícono *encima* de ese relleno.
- *   `primarySoft`  fondo teñido para estados seleccionados y pills.
- *   `primaryText`  texto/ícono del acento sobre `surface`, `background`
- *                  o sobre su propio `primarySoft`.
+ *   `primary`      solid fill (button background, selected day, FAB).
+ *   `onPrimary`    text/icon *on top of* that fill.
+ *   `primarySoft`  tinted background for selected states and pills.
+ *   `primaryText`  accent text/icon over `surface`, `background`
+ *                  or over its own `primarySoft`.
  *
- * El motivo es el contraste: un acento que se lee bien como relleno no se
- * lee como texto. Antes los componentes usaban `colors.primary` para las dos
- * cosas y lo teñían concatenando alpha al hex (`colors.primary + '15'`), lo
- * que en dark daba 2.6:1 sobre la superficie — muy por debajo del 4.5:1 de
- * WCAG AA. Todos los pares de esta paleta pasan AA en ambos esquemas.
+ * The reason is contrast: an accent that reads well as a fill doesn't read
+ * as text. Components used to use `colors.primary` for both things and tinted
+ * it by appending alpha to the hex (`colors.primary + '15'`), which in dark
+ * gave 2.6:1 over the surface — well below WCAG AA's 4.5:1. Every pair in
+ * this palette passes AA in both schemes.
  */
 export interface ThemeColors {
   primary: string;
@@ -47,14 +47,20 @@ export interface ThemeColors {
   black: string;
   background: string;
   surface: string;
+  /**
+   * Fill of a surface that sits on another surface (Card). In light it equals
+   * `surface` (the shadow separates it); in dark it is lighter, because
+   * shadows don't show and elevation reads as a lighter fill.
+   */
+  surfaceRaised: string;
   text: string;
   textLight: string;
   border: string;
   inputBackground: string;
   overlay: string;
-  /** Velo semitransparente sobre contenido propio (footer de carga de List). */
+  /** Semi-transparent veil over custom content (List's loading footer). */
   scrim: string;
-  /** Fondo de placeholder mientras carga una imagen. */
+  /** Placeholder background while an image loads. */
   skeleton: string;
 }
 
@@ -81,9 +87,9 @@ export const lightPalette: ThemeColors = {
   successSoft: '#e3f6e9',
   successText: '#116a30',
 
-  // El rojo va con texto blanco, que es lo que la gente espera de un botón
-  // destructivo. #ff3b30 no llega a 4.5:1 con blanco y obligaba a texto casi
-  // negro sobre rojo; este tono sí, y sigue leyéndose como rojo de alerta.
+  // Red goes with white text, which is what people expect from a destructive
+  // button. #ff3b30 doesn't reach 4.5:1 with white and forced near-black text
+  // over red; this shade does, and still reads as an alert red.
   error: '#dc2626',
   onError: '#ffffff',
   errorSoft: '#fdeaea',
@@ -96,19 +102,20 @@ export const lightPalette: ThemeColors = {
 
   background: '#f8f9fa',
   surface: '#ffffff',
+  surfaceRaised: '#ffffff',
   text: '#333333',
   textLight: '#666666',
   border: '#e5e7eb',
   inputBackground: '#f5f7fa',
   overlay: 'rgba(0,0,0,0.5)',
   scrim: 'rgba(248,249,250,0.8)',
-  skeleton: '#eceef1',
+  skeleton: '#e3e5e8',
 };
 
 /**
- * Los acentos de dark NO son los de light: sobre `#1e1e1e` hay que subir la
- * luminosidad del acento y bajar la del texto que va encima (por eso
- * `onPrimary` es azul oscuro acá y blanco en light).
+ * The dark accents are NOT the light ones: over `#1e1e1e` the accent's
+ * lightness has to go up and that of the text on top has to go down (which
+ * is why `onPrimary` is dark blue here and white in light).
  */
 export const darkPalette: ThemeColors = {
   ...neutral,
@@ -140,11 +147,12 @@ export const darkPalette: ThemeColors = {
 
   background: '#121212',
   surface: '#1e1e1e',
+  surfaceRaised: '#303036',
   text: '#ecedee',
   textLight: '#9ba1a6',
-  border: '#2a2a2e',
+  border: '#3a3a40',
   inputBackground: '#232326',
   overlay: 'rgba(0,0,0,0.6)',
   scrim: 'rgba(18,18,18,0.8)',
-  skeleton: '#26262a',
+  skeleton: '#44444b',
 };

package/src/theme/tokens.ts

@@ -1,13 +1,13 @@
 import { Platform, type ViewStyle } from 'react-native';
 
-// Las escalas numéricas se tipan explícitamente como `number` (no `as const`):
-// createTheme() debe poder sobreescribir cualquier valor con otro número
-// arbitrario: con literal typing, un override de `radius.md` a `999` fallaría
-// porque el tipo inferido sería el literal `8`, no `number`.
+// Numeric scales are typed explicitly as `number` (not `as const`):
+// createTheme() must be able to override any value with any other number:
+// with literal typing, overriding `radius.md` to `999` would fail because
+// the inferred type would be the literal `8`, not `number`.
 
 /**
- * Escala de espaciado. Usar siempre estos valores en vez de números mágicos
- * para que el ritmo vertical/horizontal sea consistente entre componentes.
+ * Spacing scale. Always use these values instead of magic numbers so the
+ * vertical/horizontal rhythm is consistent across components.
  */
 export const spacing: Record<'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl', number> = {
   xxs: 2,
@@ -40,8 +40,8 @@ export const fontSize: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl', number>
   xxl: 24,
 };
 
-// fontWeight sí necesita literales: TextStyle.fontWeight de RN exige un union
-// de strings específicos ('400' | '500' | ...), no `string` arbitrario.
+// fontWeight does need literals: RN's TextStyle.fontWeight requires a union
+// of specific strings ('400' | '500' | ...), not an arbitrary `string`.
 export const fontWeight = {
   regular: '400',
   medium: '500',
@@ -49,13 +49,26 @@ export const fontWeight = {
   bold: '700',
 } as const;
 
-export const lineHeight: Record<'sm' | 'md' | 'lg', number> = {
+export const lineHeight: Record<'sm' | 'md' | 'lg' | 'xl', number> = {
   sm: 16,
   md: 20,
   lg: 24,
+  xl: 30,
 };
 
-/** Duraciones en ms para Animated.timing/spring. */
+/**
+ * Tracking (letterSpacing) in points. `tight` offsets the extra room that
+ * large sizes bring by default (titles); `normal` is the system's;
+ * `wide` spaces out small caps.
+ */
+export const letterSpacing: Record<'tight' | 'normal' | 'wide', number> = {
+  tight: -0.5,
+  normal: 0,
+  /** Short, small, uppercase labels (Badge): a little room makes them legible. */
+  wide: 0.3,
+};
+
+/** Durations in ms for Animated.timing/spring. */
 export const duration: Record<'fast' | 'base' | 'slow', number> = {
   fast: 150,
   base: 200,
@@ -68,9 +81,9 @@ type ShadowStyle = Pick<
 >;
 
 /**
- * Sombras cross-platform: shadow* para iOS, elevation para Android.
- * `shadowColor` se deja en negro fijo — el color de sombra por tema es un
- * detalle demasiado fino para justificar la complejidad de resolverlo aquí.
+ * Cross-platform shadows: shadow* for iOS, elevation for Android.
+ * `shadowColor` is left fixed at black — a per-theme shadow color is too
+ * fine a detail to justify the complexity of resolving it here.
  */
 export const shadow: Record<'none' | 'sm' | 'md' | 'lg', ShadowStyle> = {
   none: Platform.select({
@@ -106,6 +119,7 @@ export const tokens = {
   fontSize,
   fontWeight,
   lineHeight,
+  letterSpacing,
   duration,
   shadow,
 };

package/src/theme/types.ts

@@ -1,14 +1,14 @@
 import type { Tokens } from './tokens';
 import type { ThemeColors } from './palettes';
 
-/** Theme resuelto: paleta de un scheme concreto + tokens compartidos. */
+/** Resolved theme: the palette of a given scheme + shared tokens. */
 export interface Theme {
   colors: ThemeColors;
   tokens: Tokens;
   scheme: 'light' | 'dark';
 }
 
-/** Par de themes light/dark que produce createTheme() y consume UIProvider. */
+/** Light/dark theme pair produced by createTheme() and consumed by UIProvider. */
 export interface ThemePair {
   light: Theme;
   dark: Theme;
@@ -18,15 +18,15 @@ export type DeepPartial<T> = {
   [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
 
-/** Acentos que se pueden definir con un solo hex vía `brand`. */
+/** Accents that can be defined with a single hex via `brand`. */
 export type BrandAccent = 'primary' | 'secondary' | 'success' | 'error' | 'warning';
 
 export interface ThemeOverrides {
   /**
-   * Un hex por acento; de cada uno se derivan sus cuatro roles (relleno, lo
-   * que va encima, el fondo tenue y la variante legible sobre `surface`) para
-   * light y para dark, con el contraste ya resuelto. Un string suelto define
-   * `primary`. Lo que se pase en `colors` gana sobre lo derivado.
+   * One hex per accent; each one derives its four roles (fill, content on top,
+   * subtle background and the variant legible on `surface`) for light and
+   * dark, with contrast already resolved. A plain string sets `primary`.
+   * Anything passed in `colors` wins over the derived values.
    */
   brand?: string | Partial<Record<BrandAccent, string>>;
   colors?: {

package/src/theme/useKeyboardField.ts

@@ -0,0 +1,33 @@
+import { useMemo, useRef, type RefObject, type ComponentRef } from 'react';
+import type { View } from 'react-native';
+import { useKeyboardHost, type KeyboardField } from './KeyboardAvoidance';
+
+/**
+ * Registers a text field with the nearest keyboard host (a Screen's content or
+ * the root UIProvider) so it stays visible above the keyboard. `boxRef` is the
+ * block that has to be seen whole: label, field and error.
+ *
+ * Call `focus()` from the TextInput's onFocus (and again when the block grows,
+ * e.g. an error shows up while typing) and `blur()` from onBlur. Inside a
+ * container that already handles the keyboard there is no host and both are
+ * no-ops.
+ */
+export function useKeyboardField(boxRef: RefObject<ComponentRef<typeof View> | null>) {
+  const host = useKeyboardHost();
+  const field = useRef<KeyboardField>({
+    measure: () =>
+      new Promise((resolve) => {
+        const node = boxRef.current;
+        if (!node) return resolve(null);
+        node.measureInWindow((_x, y, _w, height) => resolve({ y, height }));
+      }),
+  }).current;
+
+  return useMemo(
+    () => ({
+      focus: () => host?.focus(field),
+      blur: () => host?.blur(field),
+    }),
+    [host, field]
+  );
+}

package/src/theme/useReduceMotion.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+/**
+ * Follows the system "reduce motion" setting: when it is on, animations jump
+ * to their final state instead of being disabled, so callbacks and unmounting
+ * still happen the same way.
+ */
+export function useReduceMotion(): boolean {
+  const [reduceMotion, setReduceMotion] = useState(false);
+
+  useEffect(() => {
+    let alive = true;
+    // The state is only updated if the setting is on: the initial value is
+    // already `false` and a setState from false to false would cost a render per mount.
+    AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (alive && enabled) setReduceMotion(true);
+    });
+    const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);
+    return () => {
+      alive = false;
+      sub.remove();
+    };
+  }, []);
+
+  return reduceMotion;
+}