@satellatickets/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Rodriguez Carbonell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,37 @@
-# Temporary Holding Version
+# @satellatickets/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+La parte de satella-ui que no depende de la plataforma: los contratos de props de cada componente, las constantes de variantes, el contexto de tema y los hooks headless. Solo depende de `react` y de `@satellatickets/tokens`; nunca importa `react-dom` ni `react-native`.
+
+`@satellatickets/ui` lo usa para que `<Button variant="primary">` signifique lo mismo en web y en móvil. Puede instalarse solo si necesitas la lógica o los tipos sin las vistas.
+
+```ts
+import { buttonVariants, useButton, useTheme, type ButtonProps } from '@satellatickets/core';
+
+buttonVariants.variant; // ['primary', 'secondary', 'ghost', 'danger']
+
+// Comportamiento común de un botón: deshabilitado o cargando no dispara onPress.
+const { interactive, press } = useButton({ loading, onPress });
+
+// Tokens del tema activo, con la marca aplicada.
+const theme = useTheme();
+theme.color.action.primary;
+```
+
+## Qué contiene
+
+| Qué                     | Ejemplos                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| Contratos de props      | `ButtonProps`, `BadgeProps`, `BoxProps`, `StackProps`, `TextProps`, `IconProps` |
+| Constantes de variantes | `buttonVariants`, `badgeVariants`, `textVariants`, `iconSizes`                  |
+| Tema                    | `UIContext`, `useTheme`, `useColorScheme`, `useBrand`, `resolveTheme`           |
+| Hooks headless          | `useButton`                                                                     |
+
+Las variantes se exportan como arrays `as const`, además de como tipos, para poder recorrerlas: en historias, en selectores o en tests.
+
+## Instalación
+
+```bash
+npm install @satellatickets/core
+```
+
+Requiere `react >=19.0`.

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+import { ReactNode } from "react";
+import { BrandName, Theme, ThemeName, ThemeOverrides } from "@satellatickets/tokens";
+//#region src/hooks/use-button.d.ts
+export interface UseButtonOptions {
+  disabled?: boolean | undefined;
+  loading?: boolean | undefined;
+  onPress?: (() => void) | undefined;
+}
+export interface UseButtonResult {
+  disabled: boolean;
+  loading: boolean;
+  /** `false` si está deshabilitado o cargando: el botón no responde a la pulsación. */
+  interactive: boolean;
+  /** Llama a `onPress` solo si el botón es interactivo. */
+  press: () => void;
+}
+/**
+ * Comportamiento de `Button` común a web y nativo: un botón deshabilitado o que
+ * está cargando no dispara `onPress`. Cada vista añade su accesibilidad
+ * (`disabled`/`aria-busy` en web, `accessibilityState` en nativo).
+ */
+export declare function useButton({ disabled, loading, onPress }: UseButtonOptions): UseButtonResult;
+//#endregion
+//#region src/types/ui-provider.d.ts
+/** Modo de tema que acepta `UIProvider` (ADR-010). */
+export declare const themeModes: readonly ["light", "dark", "system"];
+export type ThemeMode = (typeof themeModes)[number];
+/** Esquema resuelto: siempre uno de los temas definidos en tokens. */
+export type ColorScheme = ThemeName;
+export interface UIProviderProps {
+  /** Tema claro, oscuro o el del sistema (por defecto `system`). */
+  theme?: ThemeMode | undefined;
+  /** Marca registrada en tokens. Sin marca se usa la identidad por defecto. */
+  brand?: BrandName | undefined;
+  children: ReactNode;
+}
+//#endregion
+//#region src/theme/context.d.ts
+interface UIContextValue {
+  theme: Theme;
+  colorScheme: ColorScheme;
+  mode: ThemeMode;
+  brand: BrandName | undefined;
+}
+export declare function createUIContextValue(mode: ThemeMode, systemScheme: ColorScheme, brand?: BrandName): UIContextValue;
+/** Sin `UIProvider` se usa el tema claro por defecto, para que los componentes funcionen aislados. */
+export declare const UIContext: import("react").Context<UIContextValue>;
+export declare function useUIContext(): UIContextValue;
+/** Tema resuelto (tokens con la marca aplicada). Imprescindible en las vistas nativas (ADR-008). */
+export declare function useTheme(): Theme;
+/** `'light' | 'dark'` ya resuelto, también con `theme="system"`. */
+export declare function useColorScheme(): ColorScheme;
+export declare function useBrand(): BrandName | undefined;
+//#endregion
+//#region src/theme/resolve-theme.d.ts
+/** Combina los overrides de una marca sobre un tema (ADR-010). Los arrays (sombras) se sustituyen enteros. */
+export declare function mergeTheme(base: Theme, overrides: ThemeOverrides): Theme;
+/** Tema resuelto para un esquema y una marca; memoizado para que la identidad sea estable. */
+export declare function resolveTheme(scheme: ThemeName, brand?: BrandName): Theme;
+export declare function resolveColorScheme(mode: ThemeMode, systemScheme: ColorScheme): ColorScheme;
+//#endregion
+//#region src/types/badge.d.ts
+/**
+ * Variantes de `Badge` (ADR-009): una por cada color de `color.feedback`. Las historias
+ * las usan para `argTypes` y la matriz `AllVariants`.
+ */
+export declare const badgeVariants: readonly ["success", "warning", "danger", "info"];
+export type BadgeVariant = (typeof badgeVariants)[number];
+export interface BadgeProps {
+  /** Significado del estado que etiqueta (por defecto `info`). */
+  variant?: BadgeVariant | undefined;
+  /** `data-testid` en web, `testID` en nativo. */
+  testID?: string | undefined;
+  children: ReactNode;
+}
+//#endregion
+//#region src/types/box.d.ts
+export type SpaceToken = keyof Theme['space'];
+export type RadiusToken = keyof Theme['radius'];
+export type ShadowToken = keyof Theme['shadow'];
+export type BackgroundToken = keyof Theme['color']['bg'];
+export type BorderColorToken = keyof Theme['color']['border'];
+/** Constantes para `argTypes` y matrices de historias (ADR-009). */
+export declare const spaceTokens: SpaceToken[];
+export declare const radiusTokens: RadiusToken[];
+export declare const shadowTokens: ShadowToken[];
+export declare const backgroundTokens: BackgroundToken[];
+export declare const borderColorTokens: BorderColorToken[];
+/** Contenedor base: relleno, fondo, radio, borde y sombra, siempre con tokens. */
+export interface BoxProps {
+  padding?: SpaceToken | undefined;
+  paddingX?: SpaceToken | undefined;
+  paddingY?: SpaceToken | undefined;
+  background?: BackgroundToken | undefined;
+  radius?: RadiusToken | undefined;
+  /** Borde fino (`borderWidth.thin`) con el color indicado. */
+  borderColor?: BorderColorToken | undefined;
+  shadow?: ShadowToken | undefined;
+  flex?: number | undefined;
+  /** `data-testid` en web, `testID` en nativo. */
+  testID?: string | undefined;
+  children?: ReactNode;
+}
+//#endregion
+//#region src/types/button.d.ts
+/** Variantes de `Button` (ADR-009). Las historias las usan para `argTypes` y la matriz `AllVariants`. */
+export declare const buttonVariants: {
+  readonly variant: readonly ["primary", "secondary", "ghost", "danger"];
+  readonly size: readonly ["sm", "md", "lg"];
+};
+export type ButtonVariant = (typeof buttonVariants.variant)[number];
+export type ButtonSize = (typeof buttonVariants.size)[number];
+/** Tamaño del icono (y del spinner de carga) para cada tamaño de botón. */
+export declare const buttonIconSize: {
+  readonly sm: "sm";
+  readonly md: "sm";
+  readonly lg: "md";
+};
+/**
+ * Contrato de `Button`. El conjunto de iconos lo aporta `@satellatickets/icons`,
+ * que está fuera de `core` (ADR-002), por eso el nombre es un parámetro de tipo.
+ */
+export interface ButtonProps<IconName extends string = string> {
+  /** Jerarquía visual de la acción (por defecto `primary`). */
+  variant?: ButtonVariant | undefined;
+  size?: ButtonSize | undefined;
+  /** No se puede pulsar ni enfocar. */
+  disabled?: boolean | undefined;
+  /**
+   * Acción en curso: muestra un spinner y no dispara `onPress`, pero conserva el foco
+   * y su anchura para que la interfaz no salte.
+   */
+  loading?: boolean | undefined;
+  /** Icono delante del texto. */
+  iconStart?: IconName | undefined;
+  /** Icono detrás del texto. */
+  iconEnd?: IconName | undefined;
+  /** Ocupa todo el ancho de su contenedor. */
+  fullWidth?: boolean | undefined;
+  /** Se pulsa con ratón, teclado o toque. Nombre neutral: la vista web lo mapea a `click`. */
+  onPress?: (() => void) | undefined;
+  /** Nombre accesible cuando el texto visible no basta para describir la acción. */
+  accessibilityLabel?: string | undefined;
+  /** `data-testid` en web, `testID` en nativo. */
+  testID?: string | undefined;
+  children: ReactNode;
+}
+//#endregion
+//#region src/types/text.d.ts
+export declare const textVariants: readonly ["hero", "display", "title", "heading", "subheading", "body", "bodySmall", "label", "caption", "code"];
+export type TextVariant = (typeof textVariants)[number];
+export type TextColorToken = keyof Theme['color']['text'];
+export declare const textColors: TextColorToken[];
+export declare const textAligns: readonly ["left", "center", "right"];
+export type TextAlign = (typeof textAligns)[number];
+/** Tokens que componen una variante tipográfica; ambas vistas los leen del tema. */
+export interface TextVariantStyle {
+  family: keyof Theme['font']['family'];
+  /** Tamaño; `font.lineHeight` comparte las mismas claves (lo comprueba el typecheck de las vistas). */
+  size: keyof Theme['font']['size'];
+  weight: keyof Theme['font']['weight'];
+  uppercase?: boolean;
+  /** Espaciado entre letras en px. */
+  letterSpacing?: number;
+  /** Nivel de encabezado semántico (h1–h4) si la variante es un título. */
+  headingLevel?: 1 | 2 | 3 | 4;
+}
+/** Escala tipográfica de Satella: Unbounded para titulares, Hanken Grotesk para texto, IBM Plex Mono para etiquetas. */
+export declare const textVariantStyles: Readonly<Record<TextVariant, TextVariantStyle>>;
+export interface TextProps {
+  variant?: TextVariant | undefined;
+  color?: TextColorToken | undefined;
+  align?: TextAlign | undefined;
+  /** Una sola línea con puntos suspensivos. */
+  truncate?: boolean | undefined;
+  testID?: string | undefined;
+  children?: ReactNode;
+}
+//#endregion
+//#region src/types/icon.d.ts
+export declare const iconSizes: readonly ["sm", "md", "lg"];
+export type IconSize = (typeof iconSizes)[number];
+/** Tamaño en px/puntos de cada icono. */
+export declare const iconSizePx: {
+  sm: number;
+  md: number;
+  lg: number;
+};
+/**
+ * Contrato de `Icon`. El conjunto de nombres lo aporta `@satellatickets/icons`,
+ * que está fuera de `core` (ADR-002), por eso el nombre es un parámetro de tipo.
+ */
+export interface IconProps<Name extends string = string> {
+  name: Name;
+  size?: IconSize | undefined;
+  color?: TextColorToken | undefined;
+  /** Texto alternativo. Sin él, el icono es decorativo y se oculta a los lectores de pantalla. */
+  label?: string | undefined;
+  testID?: string | undefined;
+}
+//#endregion
+//#region src/types/spinner.d.ts
+/**
+ * `Spinner` comparte la escala de `Icon`: así puede ocupar el sitio de un icono
+ * (por ejemplo, dentro de un botón que carga) sin mover el resto del contenido.
+ */
+export declare const spinnerSizes: readonly ["sm", "md", "lg"];
+export type SpinnerSize = IconSize;
+/** Tamaño en px/puntos de cada spinner. */
+export declare const spinnerSizePx: {
+  sm: number;
+  md: number;
+  lg: number;
+};
+export interface SpinnerProps {
+  size?: SpinnerSize | undefined;
+  color?: TextColorToken | undefined;
+  /**
+   * Texto que anuncian los lectores de pantalla ("Cargando eventos"). Sin él, el
+   * spinner es decorativo: úsalo así solo si el estado de carga ya se comunica de otra forma.
+   */
+  label?: string | undefined;
+  testID?: string | undefined;
+}
+//#endregion
+//#region src/types/stack.d.ts
+export declare const stackDirections: readonly ["column", "row"];
+export type StackDirection = (typeof stackDirections)[number];
+export declare const stackAligns: readonly ["stretch", "start", "center", "end"];
+export type StackAlign = (typeof stackAligns)[number];
+export declare const stackJustifies: readonly ["start", "center", "end", "between", "around"];
+export type StackJustify = (typeof stackJustifies)[number];
+/** `Box` con layout flex: dirección, separación y alineación. */
+export interface StackProps extends BoxProps {
+  direction?: StackDirection | undefined;
+  gap?: SpaceToken | undefined;
+  align?: StackAlign | undefined;
+  justify?: StackJustify | undefined;
+  wrap?: boolean | undefined;
+}
+//#endregion
+export type { UIContextValue };

package/dist/index.js

@@ -0,0 +1,249 @@
+import { createContext, useCallback, useContext } from "react";
+import { brands, themes } from "@satellatickets/tokens";
+//#region src/hooks/use-button.ts
+/**
+* Comportamiento de `Button` común a web y nativo: un botón deshabilitado o que
+* está cargando no dispara `onPress`. Cada vista añade su accesibilidad
+* (`disabled`/`aria-busy` en web, `accessibilityState` en nativo).
+*/
+function useButton({ disabled = false, loading = false, onPress }) {
+	const interactive = !disabled && !loading;
+	return {
+		disabled,
+		loading,
+		interactive,
+		press: useCallback(() => {
+			if (interactive) onPress?.();
+		}, [interactive, onPress])
+	};
+}
+//#endregion
+//#region src/theme/resolve-theme.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function merge(base, overrides) {
+	const result = { ...base };
+	for (const [key, value] of Object.entries(overrides)) {
+		if (value === void 0) continue;
+		const current = base[key];
+		result[key] = isPlainObject(current) && isPlainObject(value) ? merge(current, value) : value;
+	}
+	return result;
+}
+/** Combina los overrides de una marca sobre un tema (ADR-010). Los arrays (sombras) se sustituyen enteros. */
+function mergeTheme(base, overrides) {
+	return merge(base, overrides);
+}
+const cache = /* @__PURE__ */ new Map();
+/** Tema resuelto para un esquema y una marca; memoizado para que la identidad sea estable. */
+function resolveTheme(scheme, brand) {
+	const key = `${scheme}/${brand ?? ""}`;
+	const cached = cache.get(key);
+	if (cached) return cached;
+	const base = themes[scheme];
+	const overrides = brand === void 0 ? void 0 : brands[brand]?.[scheme];
+	const resolved = overrides === void 0 ? base : mergeTheme(base, overrides);
+	cache.set(key, resolved);
+	return resolved;
+}
+function resolveColorScheme(mode, systemScheme) {
+	return mode === "system" ? systemScheme : mode;
+}
+//#endregion
+//#region src/theme/context.ts
+function createUIContextValue(mode, systemScheme, brand) {
+	const colorScheme = resolveColorScheme(mode, systemScheme);
+	return {
+		theme: resolveTheme(colorScheme, brand),
+		colorScheme,
+		mode,
+		brand
+	};
+}
+/** Sin `UIProvider` se usa el tema claro por defecto, para que los componentes funcionen aislados. */
+const UIContext = createContext(createUIContextValue("light", "light"));
+function useUIContext() {
+	return useContext(UIContext);
+}
+/** Tema resuelto (tokens con la marca aplicada). Imprescindible en las vistas nativas (ADR-008). */
+function useTheme() {
+	return useContext(UIContext).theme;
+}
+/** `'light' | 'dark'` ya resuelto, también con `theme="system"`. */
+function useColorScheme() {
+	return useContext(UIContext).colorScheme;
+}
+function useBrand() {
+	return useContext(UIContext).brand;
+}
+//#endregion
+//#region src/types/badge.ts
+/**
+* Variantes de `Badge` (ADR-009): una por cada color de `color.feedback`. Las historias
+* las usan para `argTypes` y la matriz `AllVariants`.
+*/
+const badgeVariants = [
+	"success",
+	"warning",
+	"danger",
+	"info"
+];
+//#endregion
+//#region src/types/box.ts
+/** Constantes para `argTypes` y matrices de historias (ADR-009). */
+const spaceTokens = Object.keys(themes.light.space).map(Number);
+const radiusTokens = Object.keys(themes.light.radius);
+const shadowTokens = Object.keys(themes.light.shadow);
+const backgroundTokens = Object.keys(themes.light.color.bg);
+const borderColorTokens = Object.keys(themes.light.color.border);
+//#endregion
+//#region src/types/button.ts
+/** Variantes de `Button` (ADR-009). Las historias las usan para `argTypes` y la matriz `AllVariants`. */
+const buttonVariants = {
+	variant: [
+		"primary",
+		"secondary",
+		"ghost",
+		"danger"
+	],
+	size: [
+		"sm",
+		"md",
+		"lg"
+	]
+};
+/** Tamaño del icono (y del spinner de carga) para cada tamaño de botón. */
+const buttonIconSize = {
+	sm: "sm",
+	md: "sm",
+	lg: "md"
+};
+//#endregion
+//#region src/types/icon.ts
+const iconSizes = [
+	"sm",
+	"md",
+	"lg"
+];
+/** Tamaño en px/puntos de cada icono. */
+const iconSizePx = {
+	sm: 16,
+	md: 20,
+	lg: 24
+};
+//#endregion
+//#region src/types/spinner.ts
+/**
+* `Spinner` comparte la escala de `Icon`: así puede ocupar el sitio de un icono
+* (por ejemplo, dentro de un botón que carga) sin mover el resto del contenido.
+*/
+const spinnerSizes = iconSizes;
+/** Tamaño en px/puntos de cada spinner. */
+const spinnerSizePx = iconSizePx;
+//#endregion
+//#region src/types/stack.ts
+const stackDirections = ["column", "row"];
+const stackAligns = [
+	"stretch",
+	"start",
+	"center",
+	"end"
+];
+const stackJustifies = [
+	"start",
+	"center",
+	"end",
+	"between",
+	"around"
+];
+//#endregion
+//#region src/types/text.ts
+const textVariants = [
+	"hero",
+	"display",
+	"title",
+	"heading",
+	"subheading",
+	"body",
+	"bodySmall",
+	"label",
+	"caption",
+	"code"
+];
+const textColors = Object.keys(themes.light.color.text);
+const textAligns = [
+	"left",
+	"center",
+	"right"
+];
+/** Escala tipográfica de Satella: Unbounded para titulares, Hanken Grotesk para texto, IBM Plex Mono para etiquetas. */
+const textVariantStyles = {
+	hero: {
+		family: "display",
+		size: "hero",
+		weight: "bold",
+		headingLevel: 1
+	},
+	display: {
+		family: "display",
+		size: "display",
+		weight: "bold",
+		headingLevel: 1
+	},
+	title: {
+		family: "display",
+		size: "xxl",
+		weight: "bold",
+		headingLevel: 2
+	},
+	heading: {
+		family: "sans",
+		size: "xl",
+		weight: "semibold",
+		headingLevel: 3
+	},
+	subheading: {
+		family: "sans",
+		size: "lg",
+		weight: "semibold",
+		headingLevel: 4
+	},
+	body: {
+		family: "sans",
+		size: "md",
+		weight: "regular"
+	},
+	bodySmall: {
+		family: "sans",
+		size: "sm",
+		weight: "regular"
+	},
+	label: {
+		family: "mono",
+		size: "xs",
+		weight: "medium",
+		uppercase: true,
+		letterSpacing: 1.2
+	},
+	caption: {
+		family: "sans",
+		size: "xs",
+		weight: "regular"
+	},
+	code: {
+		family: "mono",
+		size: "sm",
+		weight: "regular"
+	}
+};
+//#endregion
+//#region src/types/ui-provider.ts
+/** Modo de tema que acepta `UIProvider` (ADR-010). */
+const themeModes = [
+	"light",
+	"dark",
+	"system"
+];
+//#endregion
+export { UIContext, backgroundTokens, badgeVariants, borderColorTokens, buttonIconSize, buttonVariants, createUIContextValue, iconSizePx, iconSizes, mergeTheme, radiusTokens, resolveColorScheme, resolveTheme, shadowTokens, spaceTokens, spinnerSizePx, spinnerSizes, stackAligns, stackDirections, stackJustifies, textAligns, textColors, textVariantStyles, textVariants, themeModes, useBrand, useButton, useColorScheme, useTheme, useUIContext };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@satellatickets/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Lógica headless de satella-ui: contratos de props, constantes de variantes, contexto de tema y hooks compartidos por React y React Native",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RobertoRodriguezCarbonell/satella-ui.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=19.0"
+  },
+  "dependencies": {
+    "@satellatickets/tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.0.0",
+    "@types/react": "19.2.18",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "jsdom": "^30.1.2",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3",
+    "@satellatickets/eslint-config": "0.0.0",
+    "@satellatickets/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run --coverage"
+  }
 }