orbital-ds 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fractalia Systems
+
+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,3 +1,50 @@
-# Temporary Holding Version
+# orbital-ds
 
-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.
+Sistema de diseño genérico. **Estructura común + temas intercambiables + primitivos**
+sobre [Base UI](https://base-ui.com) y Tailwind v4.
+
+- `styles.css` — la ESTRUCTURA: mapea variables de tema a utilidades de Tailwind y define los
+  tokens semánticos (radios, alturas de control, sombras, capas, movimiento, foco) y la capa base.
+  No lleva colores ni fuentes.
+- `themes/<tema>.css` — un TEMA: paleta (claro/oscuro), radio base y tipografía.
+  Hoy: `qratia`. Añadir otro = añadir otro fichero.
+- `ui/*` — primitivos (`orbital-ds/ui/button`, …), uno por fichero: quien no usa gráficos no
+  necesita `recharts`, quien no usa toasts no necesita `sonner`.
+
+## Uso en una app (Tailwind v4)
+
+```css
+@import 'tailwindcss';
+@plugin '@tailwindcss/typography';
+@import 'tw-animate-css';
+@import 'orbital-ds/themes/qratia.css';    /* un tema */
+@import 'orbital-ds/styles.css';           /* la estructura */
+@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
+```
+
+```tsx
+import { Button } from 'orbital-ds/ui/button';
+```
+
+## Regla
+
+Ningún componente lleva valores propios (colores, medidas, sombras, z-index, duraciones):
+pide un hueco a una variable. Para cambiar el aspecto se cambia el tema, no el componente.
+Si un componente necesita un hueco nuevo, se AÑADE el token con un valor que deje el aspecto
+como estaba.
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm verify    # typecheck + build
+pnpm dev       # recompila al guardar (para consumirlo con `link:` desde una app)
+```
+
+Peers obligatorios: `react`, `react-dom`, `@base-ui/react`, `tailwindcss`, `tailwind-merge`,
+`class-variance-authority`, `clsx`, `lucide-react`, `tw-animate-css`.
+Opcionales (solo si usas ese primitivo): `recharts` (chart), `sonner` (sonner), `next-themes` (sonner).
+
+## Licencia
+
+MIT © Fractalia Systems

package/dist/hooks/use-mobile.d.ts

@@ -0,0 +1,3 @@
+declare function useIsMobile(): boolean;
+
+export { useIsMobile };

package/dist/hooks/use-mobile.js

@@ -0,0 +1,20 @@
+import * as React from "react";
+const MOBILE_BREAKPOINT = 768;
+function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState(
+    void 0
+  );
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener("change", onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+  return !!isMobile;
+}
+export {
+  useIsMobile
+};

package/dist/lib/utils.d.ts

@@ -0,0 +1,5 @@
+import { ClassValue } from 'clsx';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/lib/utils.js

@@ -0,0 +1,8 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+export {
+  cn
+};

package/dist/styles.css

@@ -0,0 +1,347 @@
+/*
+ * orbital-ds · ESTRUCTURA común a todos los temas.
+ *
+ * Mapea las variables del tema a utilidades de Tailwind (@theme), define los
+ * tokens semánticos (radios, alturas, sombras, capas, movimiento, foco) y la
+ * capa base de interacción. NO contiene colores ni fuentes: eso lo aporta un
+ * TEMA (un fichero de `orbital-ds/themes/`). Uso en la app:
+ *
+ *   @import 'tailwindcss';
+ *   @import 'orbital-ds/themes/qratia.css';   <- un tema
+ *   @import 'orbital-ds/styles.css';          <- la estructura
+ *   @source '../node_modules/orbital-ds/dist'; <- que Tailwind vea las clases
+ */
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+
+  /*
+   * ESCALA DE TEXTO — solo utilidades ESTÁNDAR de Tailwind, sin tamaños a medida.
+   *
+   *   Display   text-4xl  36/700   nota y cifras clave
+   *   H1        text-3xl  30/700   título de vista
+   *   H2        text-xl   20/700   detalle, modal
+   *   H3        text-base 16/600   título de tarjeta
+   *   H4        text-sm   14/600   grupo dentro de tarjeta
+   *   Cuerpo    text-sm   14/400   campos y texto corriente
+   *   Fila      text-sm   14/400-500
+   *   Etiqueta  text-xs   12/600   en mayúsculas, con tracking ancho
+   *   Ayuda     text-xs   12/400   notas y validación
+   *   Dato      text-xs   12/500   mono y `tabular-nums`
+   *
+   * REGLAS: la jerarquía la hacen TAMAÑO Y PESO, nunca el color · interlineado
+   * ajustado en títulos, holgado en cuerpo · tracking negativo solo de 20px para
+   * arriba; ancho solo en mayúsculas · máximo tres niveles de título por vista ·
+   * números comparables SIEMPRE `tabular-nums`.
+   */
+
+  /*
+   * Rampa de radios, toda derivada de `--radius`: cambiar la redondez del
+   * producto es mover UN valor.
+   *   sm  chip · md  control · lg  fila · xl  tarjeta · 2xl  vista y barra
+   */
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 6px);
+  --radius-2xl: calc(var(--radius) + 8px);
+
+  /*
+   * RADIOS SEMÁNTICOS — los componentes piden el hueco, no una medida. Un tema
+   * que quiera controles menos redondos cambia ESTOS valores (p. ej.
+   * `var(--radius-md)`), sin tocar ningún componente.
+   *   control  campos, selects, pestañas, tooltips · overlay  diálogos y paneles
+   */
+  --radius-control: 2rem;
+  --radius-overlay: 2rem;
+
+  /*
+   * ALTURA DE CONTROLES — una escala para botón, campo y select, así alineados
+   * en una misma fila. Densidad distinta = cambiar estos tres valores.
+   */
+  --control-h-sm: 2rem;
+  --control-h-md: 2.25rem;
+  --control-h-lg: 2.5rem;
+
+  /*
+   * SOMBRAS SEMÁNTICAS — un hueco por tipo de pieza. `control` vale `none` hoy:
+   * el hueco existe para que un tema pueda dar relieve a los campos con solo
+   * dar valor aquí (sin tocar el componente).
+   *   control  campos y botones · raised  piezas que flotan · overlay  capas
+   */
+  --shadow-control: none;
+  --shadow-raised: var(--shadow-sm);
+  --shadow-overlay: var(--shadow-lg);
+  --shadow-popover: var(--shadow-2xl);
+
+  /*
+   * CAPAS (z-index) — tres niveles con nombre; ningún componente escribe un
+   * número. raised: pieza que sobresale de su fila · sticky: barras fijas ·
+   * overlay: menús, diálogos, paneles y tooltips.
+   */
+  --z-raised: 10;
+  --z-sticky: 20;
+  --z-overlay: 50;
+
+  /* MOVIMIENTO — dos duraciones; `reduced-motion` ya se respeta en la capa base. */
+  --motion-fast: 100ms;
+  --motion-base: 200ms;
+
+  /* FOCO — grosor del anillo de foco/error de todos los controles. */
+  --ring-width: 3px;
+
+  /* Velo tras diálogos y paneles. Un tema puede cambiar su tinte u opacidad. */
+  --color-scrim: oklch(0 0 0 / 0.8);
+
+  /*
+   * Dos sombras y no más: reposo y realce al señalar. Una tarjeta que no se
+   * puede pulsar no necesita la segunda.
+   *
+   * EN CAPAS y TINTADAS CON LA TINTA del tema (no negro): una capa tensa
+   * pegada a la pieza + una suave más lejana — es lo que hace que la tarjeta
+   * se despegue del lienzo de forma natural y armónica (patrón validado:
+   * joshwcomeau.com/css/designing-shadows).
+   */
+  --shadow-card:
+    0 1px 2px oklch(0.186 0.048 269 / 0.08),
+    0 3px 10px oklch(0.186 0.048 269 / 0.07);
+  --shadow-card-hover:
+    0 3px 6px oklch(0.186 0.048 269 / 0.1),
+    0 14px 32px oklch(0.186 0.048 269 / 0.14);
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --
inset: var(
inset);
+  --
inset-foreground: var(
inset-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  /* Texto acentuado: SIEMPRE `
link`, nunca el cian de marca — no alcanza
+   * contraste de texto sobre las superficies claras. */
+  --
link: var(
link);
+  --
link-hover: var(
link-hover);
+  --
brand: var(
brand);
+  --
brand-bright: var(
brand-bright);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /*
+   * Estado. Se exponen como colores del tema para que una etiqueta de severidad
+   * se escriba `bg-danger-soft text-danger` y nadie tenga que
+   * volver a elegir un rojo a mano.
+   */
+  --color-danger: var(--danger);
+  --color-danger-soft: var(--danger-soft);
+  --color-warning: var(--warning);
+  --color-warning-soft: var(--warning-soft);
+  --color-success: var(--success);
+  --color-success-soft: var(--success-soft);
+  --color-neutral: var(--neutral);
+  --color-neutral-soft: var(--neutral-soft);
+  --color-info: var(--info);
+  --color-info-soft: var(--info-soft);
+
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html,
+  body,
+  #app {
+    min-height: 100%;
+  }
+
+  body {
+    @apply bg-background text-foreground font-sans m-0 antialiased;
+  }
+
+  a {
+    @apply 
link hover:
link-hover;
+  }
+
+  /*
+   * EXCEPCIÓN: los enlaces del CHROME no son enlaces de texto — son destinos de
+   * navegación. Deben heredar el color de su superficie (blanco en la barra de
+   * marca, tinta en un menú), no el azul de enlace, que rompería el diseño.
+   */
+  [data-slot='sidebar'] a,
+  [data-sidebar='menu-button'],
+  [role='menuitem'],
+  [role='menuitemradio'],
+  [role='option'] {
+    color: inherit;
+  }
+  [data-slot='sidebar'] a:hover,
+  [data-sidebar='menu-button']:hover {
+    color: inherit;
+  }
+
+  ::selection {
+    background: color-mix(in oklch, var(
brand) 25%, transparent);
+  }
+
+  /*
+   * TARJETA según el design system: radio `xl`, borde de 1px y sombra de reposo.
+   * `components/ui/card.tsx` ya lleva estos valores; esta regla los GARANTIZA
+   * aunque alguien regenere el primitivo con la CLI de shadcn (que los pisa).
+   */
+  [data-slot='card'] {
+    @apply rounded-xl shadow-card ring-0;
+    border: 1px solid var(--border);
+  }
+
+  /*
+   * Estados de interacción, resueltos UNA vez para toda la aplicación
+   * (spec `sistema-de-componentes`). Ninguna feature debería volver a declarar
+   * cursor ni anillo de foco.
+   *
+   * La lista de roles cubre lo que Base UI renderiza sin <button>: opciones de
+   * menú y select, pestañas, switches, checkboxes y radios — con hover pero sin
+   * pointer quedarían «muertos» al señalar.
+   */
+  button:not(:disabled),
+  select:not(:disabled),
+  [role='button']:not([aria-disabled='true'], [data-disabled]),
+  [role='menuitem']:not([aria-disabled='true'], [data-disabled]),
+  [role='menuitemcheckbox']:not([aria-disabled='true'], [data-disabled]),
+  [role='menuitemradio']:not([aria-disabled='true'], [data-disabled]),
+  [role='option']:not([aria-disabled='true'], [data-disabled]),
+  [role='tab']:not([aria-disabled='true'], [data-disabled]),
+  [role='switch']:not([aria-disabled='true'], [data-disabled]),
+  [role='checkbox']:not([aria-disabled='true'], [data-disabled]),
+  [role='radio']:not([aria-disabled='true'], [data-disabled]),
+  [role='combobox']:not([aria-disabled='true'], [data-disabled]),
+  [role='slider']:not([aria-disabled='true'], [data-disabled]),
+  input[type='checkbox']:not(:disabled),
+  input[type='radio']:not(:disabled),
+  input[type='range']:not(:disabled),
+  a[href],
+  label[for],
+  summary {
+    @apply cursor-pointer;
+  }
+
+  button:disabled,
+  select:disabled,
+  input:disabled,
+  [aria-disabled='true'],
+  [data-disabled] {
+    @apply cursor-not-allowed;
+  }
+
+  /*
+   * Los primitivos de menú/select traen `cursor-default` como UTILIDAD, y las
+   * utilidades ganan a la capa base por orden de cascada — por eso una opción
+   * de idioma quedaba sin pointer aunque la regla de arriba la cubriera. Como
+   * los primitivos no se editan a mano, aquí el pointer se IMPONE para los
+   * roles interactivos de esos popups.
+   */
+  [role='menuitem']:not([aria-disabled='true'], [data-disabled]),
+  [role='menuitemcheckbox']:not([aria-disabled='true'], [data-disabled]),
+  [role='menuitemradio']:not([aria-disabled='true'], [data-disabled]),
+  [role='option']:not([aria-disabled='true'], [data-disabled]) {
+    cursor: pointer !important;
+  }
+
+  [aria-busy='true'] {
+    @apply cursor-progress;
+  }
+
+  /* Foco visible solo en navegación por teclado, nunca al hacer clic. */
+  :focus-visible {
+    @apply outline-ring outline-2 outline-offset-2;
+  }
+
+  /*
+   * SIDEBAR FLOTANTE según el DS (Identity Hub): la barra va despegada del
+   * borde, con el radio de vista (2xl ≈ 20px) y la sombra de realce — el efecto
+   * flotante es lo que le da el aire moderno. El primitivo trae `rounded-lg` y
+   * `shadow-sm` en su variante floating; se corrige AQUÍ (capa base), no en el
+   * componente, igual que la tarjeta.
+   */
+  [data-variant='floating'] [data-slot='sidebar-inner'] {
+    border-radius: var(--radius-2xl);
+    box-shadow: var(--shadow-card-hover);
+  }
+
+  /*
+   * TAMAÑO Y ALINEACIÓN DE LA NAVEGACIÓN — ajuste del DS sobre el primitivo
+   * (capa base, no el componente; los `!important` baten a las utilidades que
+   * el primitivo trae escritas).
+   *
+   * EXPANDIDO: filas de 40px con icono de 18px — las medidas del diseño
+   * («Revisión de llamada»), más presentes que las del shadcn por defecto.
+   *
+   * COLAPSADO: el primitivo amplió el raíl a 64px (`--sidebar-width-icon: 4rem`)
+   * pero conservó botones de 32px y `p-2` (8px) pensados para el raíl de 48px
+   * del shadcn original: quedaban pegados a la izquierda con 24px muertos.
+   * Botón a 40px y padding lateral a (64−40)/2 = 12px → centrado.
+   */
+  [data-sidebar='menu-button'] {
+    min-height: 2.5rem;
+  }
+  [data-sidebar='menu-button'] svg {
+    width: 1.125rem !important;
+    height: 1.125rem !important;
+  }
+
+  [data-collapsible='icon'] [data-slot='sidebar-header'],
+  [data-collapsible='icon'] [data-slot='sidebar-footer'],
+  [data-collapsible='icon'] [data-slot='sidebar-group'] {
+    padding-inline: 0.75rem;
+  }
+  [data-collapsible='icon'] [data-sidebar='menu-button'] {
+    width: 2.5rem !important;
+    height: 2.5rem !important;
+    padding: 0.6875rem !important; /* (40−18)/2: icono centrado */
+  }
+  /* Botones lg (marca, cuenta): dentro va una ficha de 32px → 4px de aire. */
+  [data-collapsible='icon'] [data-sidebar='menu-button'][data-size='lg'] {
+    padding: 0.25rem !important;
+  }
+
+  /*
+   * `prefers-reduced-motion` no es un detalle de cortesía: en un chrome que se
+   * pliega a diario, la animación de anchura es justo el movimiento que molesta
+   * a quien pide menos movimiento.
+   */
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      transition-duration: 0.01ms !important;
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+    }
+  }
+}