orbital-ds 0.7.0 → 0.9.0

package/contract.json

@@ -1,168 +1,226 @@
-{
-  "version": 4,
-  "descripcion": "Contrato de tema de orbital-ds: todo tema (themes/*.css) debe definir estos tokens en :root. Nombres en inglés estándar; los de shadcn sin prefijo; los propios con --ds-. baseTheme es el tema aplicado siempre (los demás se aplican encima, con ámbito).",
-  "root": [
-    "radius",
-    "background",
-    "foreground",
-    "card",
-    "card-foreground",
-    "popover",
-    "popover-foreground",
-    "primary",
-    "primary-foreground",
-    "secondary",
-    "secondary-foreground",
-    "muted",
-    "muted-foreground",
-    "accent",
-    "accent-foreground",
-    "destructive",
-    "destructive-foreground",
-    "border",
-    "input",
-    "ring",
-    "chart-1",
-    "chart-2",
-    "chart-3",
-    "chart-4",
-    "chart-5",
-    "sidebar",
-    "sidebar-foreground",
-    "sidebar-primary",
-    "sidebar-primary-foreground",
-    "sidebar-accent",
-    "sidebar-accent-foreground",
-    "sidebar-border",
-    "sidebar-ring",
-    "danger",
-    "danger-soft",
-    "warning",
-    "warning-soft",
-    "success",
-    "success-soft",
-    "info",
-    "info-soft",
-    "neutral",
-    "neutral-soft",
-    "link",
-    "link-hover",
-    "inset",
-    "inset-foreground",
-    "brand",
-    "brand-bright",
-    "ds-sidebar-icon",
-    "ds-sidebar-icon-stroke",
-    "ds-sidebar-rail-w",
-    "ds-sidebar-rail-item",
-    "ds-sidebar-logo",
-    "ds-sidebar-sep-inset"
-  ],
-  "fonts": [
-    "ds-font-sans"
-  ],
-  "dark": {
-    "descripcion": "Recomendados en .dark (si faltan, el tema hereda el valor claro y doctor avisa).",
-    "avisar_si_falta": [
-      "background",
-      "foreground",
-      "card",
-      "card-foreground",
-      "popover",
-      "popover-foreground",
-      "primary",
-      "primary-foreground",
-      "muted",
-      "muted-foreground",
-      "border",
-      "input",
-      "ring",
-      "danger",
-      "warning",
-      "success",
-      "info",
-      "link"
-    ]
-  },
-  "baseTheme": "qratia",
-  "brand": {
-    "descripcion": "Grupo ESTABLE de variables que una app suele personalizar en su fichero de marca (brand.css). Renombrar o quitar una es versión MAYOR. Todas están también en `root` salvo las --ds-*.",
-    "tokens": [
-      {
-        "name": "primary",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "color de acción principal (botones, foco)"
-      },
-      {
-        "name": "primary-foreground",
-        "example": "#ffffff",
-        "about": "texto sobre el color principal (comprueba el contraste)"
-      },
-      {
-        "name": "ring",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "anillo de foco; suele ir igual que primary"
-      },
-      {
-        "name": "link",
-        "example": "oklch(0.5 0.15 260)",
-        "about": "texto de enlace: más oscuro que primary para tener contraste"
-      },
-      {
-        "name": "link-hover",
-        "example": "oklch(0.42 0.13 260)",
-        "about": "enlace al pasar el ratón"
-      },
-      {
-        "name": "brand",
-        "example": "oklch(0.7 0.13 220)",
-        "about": "acento de marca (detalles, selección)"
-      },
-      {
-        "name": "brand-bright",
-        "example": "oklch(0.8 0.13 220)",
-        "about": "acento de marca sobre fondos oscuros"
-      },
-      {
-        "name": "sidebar-primary",
-        "example": "oklch(0.8 0.13 220)",
-        "about": "acento dentro del sidebar"
-      },
-      {
-        "name": "sidebar-primary-foreground",
-        "example": "#04121c",
-        "about": "texto sobre el acento del sidebar"
-      },
-      {
-        "name": "sidebar-accent-foreground",
-        "example": "oklch(0.85 0.1 220)",
-        "about": "texto del destino activo del sidebar"
-      },
-      {
-        "name": "accent-foreground",
-        "example": "oklch(0.5 0.15 260)",
-        "about": "texto sobre superficies de acento suave"
-      },
-      {
-        "name": "chart-1",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "primera serie de las gráficas: la marca"
-      },
-      {
-        "name": "radius",
-        "example": "12px",
-        "about": "redondez base (en temas cuya rampa deriva de ella)"
-      },
-      {
-        "name": "ds-font-sans",
-        "example": "'Inter', system-ui, sans-serif",
-        "about": "fuente del cuerpo (carga la fuente en tu app)"
-      },
-      {
-        "name": "ds-font-display",
-        "example": "'Sora', system-ui, sans-serif",
-        "about": "fuente de los titulares"
-      }
-    ]
-  }
-}
+{
+  "version": 5,
+  "descripcion": "Contrato de tema de orbital-ds: todo tema (themes/*.css) debe definir estos tokens en :root. Nombres en inglés estándar; los de shadcn sin prefijo; los propios con --ds-. baseTheme es el tema aplicado siempre (los demás se aplican encima, con ámbito).",
+  "root": [
+    "radius",
+    "background",
+    "foreground",
+    "card",
+    "card-foreground",
+    "popover",
+    "popover-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "destructive",
+    "destructive-foreground",
+    "border",
+    "input",
+    "ring",
+    "chart-1",
+    "chart-2",
+    "chart-3",
+    "chart-4",
+    "chart-5",
+    "sidebar",
+    "sidebar-foreground",
+    "sidebar-primary",
+    "sidebar-primary-foreground",
+    "sidebar-accent",
+    "sidebar-accent-foreground",
+    "sidebar-border",
+    "sidebar-ring",
+    "danger",
+    "danger-soft",
+    "warning",
+    "warning-soft",
+    "success",
+    "success-soft",
+    "info",
+    "info-soft",
+    "neutral",
+    "neutral-soft",
+    "link",
+    "link-hover",
+    "inset",
+    "inset-foreground",
+    "brand",
+    "brand-bright",
+    "ds-sidebar-icon",
+    "ds-sidebar-icon-stroke",
+    "ds-sidebar-rail-w",
+    "ds-sidebar-rail-item",
+    "ds-sidebar-logo",
+    "ds-sidebar-sep-inset"
+  ],
+  "fonts": [
+    "ds-font-sans"
+  ],
+  "dark": {
+    "descripcion": "Recomendados en .dark (si faltan, el tema hereda el valor claro y doctor avisa).",
+    "avisar_si_falta": [
+      "background",
+      "foreground",
+      "card",
+      "card-foreground",
+      "popover",
+      "popover-foreground",
+      "primary",
+      "primary-foreground",
+      "muted",
+      "muted-foreground",
+      "border",
+      "input",
+      "ring",
+      "danger",
+      "warning",
+      "success",
+      "info",
+      "link"
+    ]
+  },
+  "baseTheme": "qratia",
+  "slotFamilies": {
+    "descripcion": "Piezas hermanas: si la PERSONALIDAD de un tema estiliza una, debe estilizar todas, o se verán distintas en la misma pantalla. Error en temas con «conformance»: «strict» en su ficha; aviso en los demás.",
+    "families": {
+      "choice": [
+        "checkbox",
+        "radio-group-item"
+      ],
+      "field": [
+        "input",
+        "textarea",
+        "select-trigger",
+        "native-select",
+        "input-group",
+        "input-otp-slot"
+      ],
+      "modal": [
+        "dialog-content",
+        "sheet-content",
+        "alert-dialog-content",
+        "drawer-popup"
+      ],
+      "floating": [
+        "popover-content",
+        "dropdown-menu-content",
+        "dropdown-menu-sub-content",
+        "select-content",
+        "context-menu-content",
+        "context-menu-sub-content",
+        "menubar-content",
+        "menubar-sub-content",
+        "hover-card-content",
+        "combobox-content",
+        "navigation-menu-popup"
+      ],
+      "title": [
+        "card-title",
+        "dialog-title",
+        "sheet-title",
+        "alert-dialog-title",
+        "drawer-title",
+        "empty-title"
+      ],
+      "toggle": [
+        "tabs-trigger",
+        "toggle",
+        "toggle-group-item"
+      ],
+      "track": [
+        "progress",
+        "slider-track"
+      ],
+      "notice": [
+        "alert",
+        "banner",
+        "toast"
+      ]
+    }
+  },
+  "brand": {
+    "descripcion": "Grupo ESTABLE de variables que una app suele personalizar en su fichero de marca (brand.css). Renombrar o quitar una es versión MAYOR. Todas están también en `root` salvo las --ds-*.",
+    "tokens": [
+      {
+        "name": "primary",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "color de acción principal (botones, foco)"
+      },
+      {
+        "name": "primary-foreground",
+        "example": "#ffffff",
+        "about": "texto sobre el color principal (comprueba el contraste)"
+      },
+      {
+        "name": "ring",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "anillo de foco; suele ir igual que primary"
+      },
+      {
+        "name": "link",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto de enlace: más oscuro que primary para tener contraste"
+      },
+      {
+        "name": "link-hover",
+        "example": "oklch(0.42 0.13 260)",
+        "about": "enlace al pasar el ratón"
+      },
+      {
+        "name": "brand",
+        "example": "oklch(0.7 0.13 220)",
+        "about": "acento de marca (detalles, selección)"
+      },
+      {
+        "name": "brand-bright",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento de marca sobre fondos oscuros"
+      },
+      {
+        "name": "sidebar-primary",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento dentro del sidebar"
+      },
+      {
+        "name": "sidebar-primary-foreground",
+        "example": "#04121c",
+        "about": "texto sobre el acento del sidebar"
+      },
+      {
+        "name": "sidebar-accent-foreground",
+        "example": "oklch(0.85 0.1 220)",
+        "about": "texto del destino activo del sidebar"
+      },
+      {
+        "name": "accent-foreground",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto sobre superficies de acento suave"
+      },
+      {
+        "name": "chart-1",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "primera serie de las gráficas: la marca"
+      },
+      {
+        "name": "radius",
+        "example": "12px",
+        "about": "redondez base (en temas cuya rampa deriva de ella)"
+      },
+      {
+        "name": "ds-font-sans",
+        "example": "'Inter', system-ui, sans-serif",
+        "about": "fuente del cuerpo (carga la fuente en tu app)"
+      },
+      {
+        "name": "ds-font-display",
+        "example": "'Sora', system-ui, sans-serif",
+        "about": "fuente de los titulares"
+      }
+    ]
+  }
+}

package/dist/hooks/use-ds-messages.d.ts

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { DsMessages } from '../lib/i18n.js';
+
+/** Textos activos de orbital-ds (los fija `DsI18nProvider`; sin él, inglés). */
+declare const DsMessagesContext: React.Context<{
+    close: string;
+    closeNotification: string;
+    loading: string;
+    breadcrumb: string;
+    breadcrumbMore: string;
+    pagination: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    paginationPreviousLabel: string;
+    paginationNextLabel: string;
+    paginationMore: string;
+    carousel: string;
+    carouselSlide: string;
+    carouselPrevious: string;
+    carouselNext: string;
+    commandTitle: string;
+    commandDescription: string;
+    scrollToEnd: string;
+    scrollToStart: string;
+    sidebarToggle: string;
+    sidebarTitle: string;
+    sidebarDescription: string;
+    questionnairePrevious: string;
+    questionnaireSkip: string;
+    questionnaireNext: string;
+    questionnaireSubmit: string;
+}>;
+/** Textos de los componentes en el idioma activo. */
+declare function useDsMessages(): DsMessages;
+
+export { DsMessagesContext, useDsMessages };

package/dist/hooks/use-ds-messages.js

@@ -0,0 +1,12 @@
+import * as React from "react";
+import { dsCatalogs, DS_DEFAULT_LOCALE } from "../lib/i18n";
+const DsMessagesContext = React.createContext(
+  dsCatalogs[DS_DEFAULT_LOCALE]
+);
+function useDsMessages() {
+  return React.useContext(DsMessagesContext);
+}
+export {
+  DsMessagesContext,
+  useDsMessages
+};

package/dist/hooks/use-ds-motion.d.ts

@@ -0,0 +1,17 @@
+import { DsMotion, DsDuration, DsEase, DsTransition } from '../lib/motion.js';
+
+/**
+ * Transición del tema activo para Motion (u otra librería): se recalcula al cambiar
+ * de tema o de piel (atributos `class`, `data-theme` y `style` de <html>) y al
+ * cambiar la preferencia de movimiento reducido.
+ */
+declare function useDsTransition(duration?: DsDuration, ease?: DsEase): DsTransition;
+/**
+ * Sistema de movimiento completo del tema activo, con presets para Motion:
+ *   const m = useDsMotion()
+ *   <motion.ul variants={...} {...m.list}> <motion.li {...m.fadeUp} /> </motion.ul>
+ *   <motion.button {...m.press} />
+ */
+declare function useDsMotion(): DsMotion;
+
+export { useDsMotion, useDsTransition };

package/dist/hooks/use-ds-motion.js

@@ -0,0 +1,50 @@
+import * as React from "react";
+import {
+  readDsTransition,
+  readDsMotion
+} from "../lib/motion";
+function useDsTransition(duration = "base", ease = "standard") {
+  const [transition, setTransition] = React.useState(
+    () => readDsTransition(duration, ease)
+  );
+  React.useEffect(() => {
+    const update = () => setTransition(readDsTransition(duration, ease));
+    update();
+    const root = document.documentElement;
+    const observer = new MutationObserver(update);
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: ["class", "data-theme", "style"]
+    });
+    const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
+    mql.addEventListener("change", update);
+    return () => {
+      observer.disconnect();
+      mql.removeEventListener("change", update);
+    };
+  }, [duration, ease]);
+  return transition;
+}
+function useDsMotion() {
+  const [motion, setMotion] = React.useState(() => readDsMotion());
+  React.useEffect(() => {
+    const update = () => setMotion(readDsMotion());
+    update();
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "data-theme", "style"]
+    });
+    const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
+    mql.addEventListener("change", update);
+    return () => {
+      observer.disconnect();
+      mql.removeEventListener("change", update);
+    };
+  }, []);
+  return motion;
+}
+export {
+  useDsMotion,
+  useDsTransition
+};

package/dist/lib/i18n.d.ts

@@ -0,0 +1,46 @@
+declare const DS_LOCALES: readonly ["en", "es", "pt-BR"];
+type DsLocale = (typeof DS_LOCALES)[number];
+declare const DS_DEFAULT_LOCALE: DsLocale;
+declare const en: {
+    close: string;
+    closeNotification: string;
+    loading: string;
+    breadcrumb: string;
+    breadcrumbMore: string;
+    pagination: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    paginationPreviousLabel: string;
+    paginationNextLabel: string;
+    paginationMore: string;
+    carousel: string;
+    carouselSlide: string;
+    carouselPrevious: string;
+    carouselNext: string;
+    commandTitle: string;
+    commandDescription: string;
+    scrollToEnd: string;
+    scrollToStart: string;
+    sidebarToggle: string;
+    sidebarTitle: string;
+    sidebarDescription: string;
+    questionnairePrevious: string;
+    questionnaireSkip: string;
+    questionnaireNext: string;
+    questionnaireSubmit: string;
+};
+type DsMessages = typeof en;
+type DsMessageKey = keyof DsMessages;
+/** Catálogos incluidos. Una app puede usarlos para sembrar los suyos (p. ej. en i18next). */
+declare const dsCatalogs: Record<DsLocale, DsMessages>;
+/**
+ * Resuelve una etiqueta BCP 47 (`es-CO`, `pt-PT`, `fr`…) contra los idiomas incluidos:
+ * coincidencia exacta → mismo idioma base → inglés. Misma regla que la plantilla.
+ */
+declare function resolveDsLocale(tag: string | null | undefined): DsLocale;
+/** Textos para un idioma, con sobrescrituras opcionales. */
+declare function dsMessagesFor(tag?: string | null, overrides?: Partial<DsMessages>): DsMessages;
+declare const DS_RTL_LANGS: readonly ["ar", "he", "fa", "ur", "ps", "sd", "ug", "yi", "dv", "ckb"];
+declare function dsDirection(tag: string | null | undefined): "ltr" | "rtl";
+
+export { DS_DEFAULT_LOCALE, DS_LOCALES, DS_RTL_LANGS, type DsLocale, type DsMessageKey, type DsMessages, dsCatalogs, dsDirection, dsMessagesFor, resolveDsLocale };

package/dist/lib/i18n.js

@@ -0,0 +1,109 @@
+const DS_LOCALES = ["en", "es", "pt-BR"];
+const DS_DEFAULT_LOCALE = "en";
+const en = {
+  close: "Close",
+  closeNotification: "Close notification",
+  loading: "Loading",
+  breadcrumb: "Breadcrumb",
+  breadcrumbMore: "More",
+  pagination: "Pagination",
+  paginationPrevious: "Previous",
+  paginationNext: "Next",
+  paginationPreviousLabel: "Go to previous page",
+  paginationNextLabel: "Go to next page",
+  paginationMore: "More pages",
+  carousel: "carousel",
+  carouselSlide: "slide",
+  carouselPrevious: "Previous slide",
+  carouselNext: "Next slide",
+  commandTitle: "Command palette",
+  commandDescription: "Search for a command to run\u2026",
+  scrollToEnd: "Scroll to end",
+  scrollToStart: "Scroll to start",
+  sidebarToggle: "Toggle sidebar",
+  sidebarTitle: "Sidebar",
+  sidebarDescription: "Displays the mobile sidebar.",
+  questionnairePrevious: "Previous",
+  questionnaireSkip: "Skip",
+  questionnaireNext: "Next",
+  questionnaireSubmit: "Submit"
+};
+const es = {
+  close: "Cerrar",
+  closeNotification: "Cerrar aviso",
+  loading: "Cargando",
+  breadcrumb: "Ruta de navegaci\xF3n",
+  breadcrumbMore: "M\xE1s",
+  pagination: "Paginaci\xF3n",
+  paginationPrevious: "Anterior",
+  paginationNext: "Siguiente",
+  paginationPreviousLabel: "Ir a la p\xE1gina anterior",
+  paginationNextLabel: "Ir a la p\xE1gina siguiente",
+  paginationMore: "M\xE1s p\xE1ginas",
+  carousel: "carrusel",
+  carouselSlide: "diapositiva",
+  carouselPrevious: "Diapositiva anterior",
+  carouselNext: "Diapositiva siguiente",
+  commandTitle: "Paleta de comandos",
+  commandDescription: "Busca un comando para ejecutar\u2026",
+  scrollToEnd: "Ir al final",
+  scrollToStart: "Ir al principio",
+  sidebarToggle: "Mostrar u ocultar el lateral",
+  sidebarTitle: "Lateral",
+  sidebarDescription: "Muestra el lateral en el m\xF3vil.",
+  questionnairePrevious: "Anterior",
+  questionnaireSkip: "Omitir",
+  questionnaireNext: "Siguiente",
+  questionnaireSubmit: "Enviar"
+};
+const ptBR = {
+  close: "Fechar",
+  closeNotification: "Fechar aviso",
+  loading: "Carregando",
+  breadcrumb: "Trilha de navega\xE7\xE3o",
+  breadcrumbMore: "Mais",
+  pagination: "Pagina\xE7\xE3o",
+  paginationPrevious: "Anterior",
+  paginationNext: "Pr\xF3xima",
+  paginationPreviousLabel: "Ir para a p\xE1gina anterior",
+  paginationNextLabel: "Ir para a pr\xF3xima p\xE1gina",
+  paginationMore: "Mais p\xE1ginas",
+  carousel: "carrossel",
+  carouselSlide: "slide",
+  carouselPrevious: "Slide anterior",
+  carouselNext: "Pr\xF3ximo slide",
+  commandTitle: "Paleta de comandos",
+  commandDescription: "Pesquise um comando para executar\u2026",
+  scrollToEnd: "Ir para o final",
+  scrollToStart: "Ir para o in\xEDcio",
+  sidebarToggle: "Mostrar ou ocultar a barra lateral",
+  sidebarTitle: "Barra lateral",
+  sidebarDescription: "Mostra a barra lateral no celular.",
+  questionnairePrevious: "Anterior",
+  questionnaireSkip: "Pular",
+  questionnaireNext: "Pr\xF3xima",
+  questionnaireSubmit: "Enviar"
+};
+const dsCatalogs = { en, es, "pt-BR": ptBR };
+function resolveDsLocale(tag) {
+  if (!tag) return DS_DEFAULT_LOCALE;
+  const base = tag.split("-")[0];
+  return DS_LOCALES.find((l) => l === tag) ?? DS_LOCALES.find((l) => l.split("-")[0] === base) ?? DS_DEFAULT_LOCALE;
+}
+function dsMessagesFor(tag, overrides) {
+  return { ...dsCatalogs[resolveDsLocale(tag)], ...overrides };
+}
+const DS_RTL_LANGS = ["ar", "he", "fa", "ur", "ps", "sd", "ug", "yi", "dv", "ckb"];
+function dsDirection(tag) {
+  const base = (tag ?? "").toLowerCase().split("-")[0];
+  return DS_RTL_LANGS.includes(base) ? "rtl" : "ltr";
+}
+export {
+  DS_DEFAULT_LOCALE,
+  DS_LOCALES,
+  DS_RTL_LANGS,
+  dsCatalogs,
+  dsDirection,
+  dsMessagesFor,
+  resolveDsLocale
+};