@drakkar.software/octospaces-ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import React from 'react';
+
+/**
+ * Theme contract for `@drakkar.software/octospaces-ui`.
+ *
+ * The package ships NO theme VALUES — only these type definitions. The host app
+ * constructs a concrete {@link Theme} object (with its own palette, tokens, and
+ * scheme logic) and passes it to `<OctoSpacesThemeProvider theme={…}>` at the root.
+ *
+ * The {@link Palette} interface is the SUPERSET of OctoChat + OctoVault so the UI
+ * primitives work correctly in both apps. Apps that don't use vault-specific keys
+ * (like `editorCanvas`) can safely set them to a sensible default.
+ */
+/** The active color scheme. Passed as part of `Theme.scheme`. */
+type ColorScheme = 'light' | 'dark';
+/**
+ * Full color palette contract. OctoVault's palette is the superset. OctoChat apps
+ * add `editorCanvas`, `tooltipBg`, `onTooltip` as they migrate to the shared UI.
+ *
+ * All colors are CSS/RN color strings (hex, rgba, or named color tokens).
+ */
+interface Palette {
+    background: string;
+    surface: string;
+    surfaceElevated: string;
+    surfaceModal: string;
+    surfaceInput: string;
+    sidebar: string;
+    sidebarActive: string;
+    border: string;
+    borderSubtle: string;
+    borderStrong: string;
+    text: string;
+    textSecondary: string;
+    textTertiary: string;
+    textDisabled: string;
+    textInverse: string;
+    textOnPrimary: string;
+    primary: string;
+    primaryHover: string;
+    primaryMuted: string;
+    primarySubtle: string;
+    success: string;
+    successMuted: string;
+    warning: string;
+    warningMuted: string;
+    danger: string;
+    dangerMuted: string;
+    info: string;
+    infoMuted: string;
+    presenceOnline: string;
+    presenceAway: string;
+    presenceBusy: string;
+    presenceOffline: string;
+    verificationVerified: string;
+    verificationPartial: string;
+    verificationNone: string;
+    overlay: string;
+    shadow: string;
+    focus: string;
+    skeleton: string;
+    skeletonShimmer: string;
+    editorCanvas: string;
+    tooltipBg: string;
+    onTooltip: string;
+}
+/**
+ * Static spacing scale. Host app provides an object with numeric pixel values
+ * keyed by token name. E.g. `{ '0': 0, '1': 4, '2': 8, '3': 12, '4': 16, … }`.
+ */
+type Spacing = Record<string, number>;
+/**
+ * Border-radius scale.
+ */
+type Radii = Record<string, number | string>;
+/**
+ * Typography scale: font sizes, line heights, weights — keyed by variant name.
+ */
+interface TypeScale {
+    size: number;
+    lineHeight: number;
+    weight?: string | number;
+    letterSpacing?: number;
+}
+type Typography = Record<string, TypeScale>;
+/**
+ * Font family config. Keys are semantic names; values are font-family strings.
+ */
+type Fonts = Record<string, string>;
+/** Easing curve definitions (e.g. for Reanimated `withTiming`). */
+type Easing = Record<string, number[]>;
+/**
+ * Motion token: duration + easing pairs keyed by animation name.
+ */
+interface MotionToken {
+    duration: number;
+    easing?: number[];
+}
+type Motion = Record<string, MotionToken>;
+/** Shadow / elevation definitions. */
+interface ShadowToken {
+    shadowColor?: string;
+    shadowOffset?: {
+        width: number;
+        height: number;
+    };
+    shadowOpacity?: number;
+    shadowRadius?: number;
+    elevation?: number;
+}
+type Shadows = Record<string, ShadowToken>;
+/** Layout constants (screen margins, nav heights, etc.). */
+type Layout = Record<string, number>;
+/** Opacity scale. */
+type Opacity = Record<string, number>;
+/** Named color swatches (beyond the palette — brand accents, label colors). */
+type Swatches = Record<string, string>;
+/** z-index layers. */
+type Layers = Record<string, number>;
+/** Letter-spacing presets keyed by variant name. */
+type LabelTracking = Record<string, number>;
+/**
+ * The complete Theme object the host app constructs and injects.
+ * All primitives in this package read ONLY from this injected Theme.
+ */
+interface Theme {
+    scheme: ColorScheme;
+    colors: Palette;
+    spacing: Spacing;
+    radii: Radii;
+    type: Typography;
+    fonts: Fonts;
+    motion: Motion;
+    shadows: Shadows;
+    layout: Layout;
+    opacity: Opacity;
+    swatches: Swatches;
+    layers: Layers;
+    easing: Easing;
+    labelTracking: LabelTracking;
+}
+
+/**
+ * Theme injection plumbing — provider + hook.
+ *
+ * The package carries ZERO theme values. The host app builds a concrete {@link Theme}
+ * and wraps its tree in `<OctoSpacesThemeProvider theme={resolvedTheme}>`.
+ * All primitives then call `useOctoSpacesTheme()` to read the active theme.
+ */
+
+interface OctoSpacesThemeProviderProps {
+    theme: Theme;
+    children: React.ReactNode;
+}
+/**
+ * Wrap your root component with this provider to inject the resolved Theme into
+ * every primitive from `@drakkar.software/octospaces-ui`.
+ *
+ * @example
+ * ```tsx
+ * import { OctoSpacesThemeProvider } from '@drakkar.software/octospaces-ui';
+ * import { resolvedTheme } from '@/theme'; // your app's theme
+ *
+ * export default function App() {
+ *   return (
+ *     <OctoSpacesThemeProvider theme={resolvedTheme}>
+ *       <RootNavigator />
+ *     </OctoSpacesThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function OctoSpacesThemeProvider({ theme, children }: OctoSpacesThemeProviderProps): React.JSX.Element;
+/**
+ * Read the active theme. Throws if called outside an `<OctoSpacesThemeProvider>` —
+ * this is intentional: a missing provider means primitives have no colors/spacing,
+ * so a hard failure with a clear message is better than a silent rendering bug.
+ */
+declare function useOctoSpacesTheme(): Theme;
+
+/**
+ * Pure palette-helper functions over a {@link Palette}. No theme values live here —
+ * only functions that DERIVE from the injected palette (or from passed-in colors).
+ *
+ * Import these from `@drakkar.software/octospaces-ui` (re-exported by `src/index.ts`).
+ */
+
+/** Map a presence status string to the corresponding palette color. */
+declare function presenceColor(palette: Palette, status: 'online' | 'away' | 'busy' | 'offline' | string): string;
+/** Map a verification level to the corresponding palette color. */
+declare function verificationColor(palette: Palette, level: 'verified' | 'partial' | 'none' | string): string;
+/** Stable avatar background tint derived from a userId string. */
+declare function avatarTint(palette: Palette, userId: string): string;
+/** Look up a named swatch; falls back to `palette.primary` if absent. */
+declare function swatch(theme: Theme, name: string): string;
+/** Derive a `borderColor` value for a "paper" (elevated surface) border. */
+declare function paperBorder(palette: Palette): string;
+/** Build a glow shadow token from a base color (used for focus rings, highlights). */
+declare function glowShadow(color: string, radius?: number, opacity?: number): ShadowToken;
+/** Style object for a keyboard-focus indicator (web + React Native). */
+declare function focusRingStyle(palette: Palette, width?: number): {
+    borderWidth: number;
+    borderColor: string;
+    borderStyle: 'solid';
+};
+/** Map a semantic status name to its palette color. */
+declare function statusColor(palette: Palette, status: 'success' | 'warning' | 'danger' | 'info' | string, muted?: boolean): string;
+
+export { type ColorScheme, type Easing, type Fonts, type LabelTracking, type Layers, type Layout, type Motion, type MotionToken, OctoSpacesThemeProvider, type OctoSpacesThemeProviderProps, type Opacity, type Palette, type Radii, type ShadowToken, type Shadows, type Spacing, type Swatches, type Theme, type TypeScale, type Typography, avatarTint, focusRingStyle, glowShadow, paperBorder, presenceColor, statusColor, swatch, useOctoSpacesTheme, verificationColor };

package/dist/index.js

@@ -0,0 +1,107 @@
+// src/theme/provider.tsx
+import React, { createContext, useContext } from "react";
+var ThemeContext = createContext(null);
+function OctoSpacesThemeProvider({ theme, children }) {
+  return /* @__PURE__ */ React.createElement(ThemeContext.Provider, { value: theme }, children);
+}
+function useOctoSpacesTheme() {
+  const theme = useContext(ThemeContext);
+  if (!theme) {
+    throw new Error(
+      "[octospaces-ui] useOctoSpacesTheme() called outside of <OctoSpacesThemeProvider>. Wrap your root component with <OctoSpacesThemeProvider theme={\u2026}>."
+    );
+  }
+  return theme;
+}
+
+// src/theme/helpers.ts
+function presenceColor(palette, status) {
+  switch (status) {
+    case "online":
+      return palette.presenceOnline;
+    case "away":
+      return palette.presenceAway;
+    case "busy":
+      return palette.presenceBusy;
+    default:
+      return palette.presenceOffline;
+  }
+}
+function verificationColor(palette, level) {
+  switch (level) {
+    case "verified":
+      return palette.verificationVerified;
+    case "partial":
+      return palette.verificationPartial;
+    default:
+      return palette.verificationNone;
+  }
+}
+var AVATAR_TINT_KEYS = [
+  "primary",
+  "success",
+  "warning",
+  "danger",
+  "info"
+];
+function avatarTint(palette, userId) {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) hash = hash * 31 + userId.charCodeAt(i) | 0;
+  const key = AVATAR_TINT_KEYS[Math.abs(hash) % AVATAR_TINT_KEYS.length];
+  return palette[key] ?? palette.primary;
+}
+function swatch(theme, name) {
+  return theme.swatches[name] ?? theme.colors.primary;
+}
+function paperBorder(palette) {
+  return palette.borderSubtle;
+}
+function glowShadow(color, radius = 8, opacity = 0.4) {
+  return {
+    shadowColor: color,
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: opacity,
+    shadowRadius: radius,
+    elevation: 4
+  };
+}
+function focusRingStyle(palette, width = 2) {
+  return { borderWidth: width, borderColor: palette.focus, borderStyle: "solid" };
+}
+function statusColor(palette, status, muted = false) {
+  if (muted) {
+    switch (status) {
+      case "success":
+        return palette.successMuted;
+      case "warning":
+        return palette.warningMuted;
+      case "danger":
+        return palette.dangerMuted;
+      default:
+        return palette.infoMuted;
+    }
+  }
+  switch (status) {
+    case "success":
+      return palette.success;
+    case "warning":
+      return palette.warning;
+    case "danger":
+      return palette.danger;
+    default:
+      return palette.info;
+  }
+}
+export {
+  OctoSpacesThemeProvider,
+  avatarTint,
+  focusRingStyle,
+  glowShadow,
+  paperBorder,
+  presenceColor,
+  statusColor,
+  swatch,
+  useOctoSpacesTheme,
+  verificationColor
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme/provider.tsx","../src/theme/helpers.ts"],"sourcesContent":["/**\n * Theme injection plumbing — provider + hook.\n *\n * The package carries ZERO theme values. The host app builds a concrete {@link Theme}\n * and wraps its tree in `<OctoSpacesThemeProvider theme={resolvedTheme}>`.\n * All primitives then call `useOctoSpacesTheme()` to read the active theme.\n */\nimport React, { createContext, useContext } from 'react';\nimport type { Theme } from './types.js';\n\nconst ThemeContext = createContext<Theme | null>(null);\n\nexport interface OctoSpacesThemeProviderProps {\n  theme: Theme;\n  children: React.ReactNode;\n}\n\n/**\n * Wrap your root component with this provider to inject the resolved Theme into\n * every primitive from `@drakkar.software/octospaces-ui`.\n *\n * @example\n * ```tsx\n * import { OctoSpacesThemeProvider } from '@drakkar.software/octospaces-ui';\n * import { resolvedTheme } from '@/theme'; // your app's theme\n *\n * export default function App() {\n *   return (\n *     <OctoSpacesThemeProvider theme={resolvedTheme}>\n *       <RootNavigator />\n *     </OctoSpacesThemeProvider>\n *   );\n * }\n * ```\n */\nexport function OctoSpacesThemeProvider({ theme, children }: OctoSpacesThemeProviderProps) {\n  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;\n}\n\n/**\n * Read the active theme. Throws if called outside an `<OctoSpacesThemeProvider>` —\n * this is intentional: a missing provider means primitives have no colors/spacing,\n * so a hard failure with a clear message is better than a silent rendering bug.\n */\nexport function useOctoSpacesTheme(): Theme {\n  const theme = useContext(ThemeContext);\n  if (!theme) {\n    throw new Error(\n      '[octospaces-ui] useOctoSpacesTheme() called outside of <OctoSpacesThemeProvider>. ' +\n        'Wrap your root component with <OctoSpacesThemeProvider theme={…}>.',\n    );\n  }\n  return theme;\n}\n","/**\n * Pure palette-helper functions over a {@link Palette}. No theme values live here —\n * only functions that DERIVE from the injected palette (or from passed-in colors).\n *\n * Import these from `@drakkar.software/octospaces-ui` (re-exported by `src/index.ts`).\n */\nimport type { Palette, ShadowToken, Theme } from './types.js';\n\n// ── Presence ──────────────────────────────────────────────────────────────────\n\n/** Map a presence status string to the corresponding palette color. */\nexport function presenceColor(\n  palette: Palette,\n  status: 'online' | 'away' | 'busy' | 'offline' | string,\n): string {\n  switch (status) {\n    case 'online': return palette.presenceOnline;\n    case 'away':   return palette.presenceAway;\n    case 'busy':   return palette.presenceBusy;\n    default:       return palette.presenceOffline;\n  }\n}\n\n// ── Verification ──────────────────────────────────────────────────────────────\n\n/** Map a verification level to the corresponding palette color. */\nexport function verificationColor(\n  palette: Palette,\n  level: 'verified' | 'partial' | 'none' | string,\n): string {\n  switch (level) {\n    case 'verified': return palette.verificationVerified;\n    case 'partial':  return palette.verificationPartial;\n    default:         return palette.verificationNone;\n  }\n}\n\n// ── Avatar ────────────────────────────────────────────────────────────────────\n\nconst AVATAR_TINT_KEYS = [\n  'primary', 'success', 'warning', 'danger', 'info',\n] as const;\n\n/** Stable avatar background tint derived from a userId string. */\nexport function avatarTint(palette: Palette, userId: string): string {\n  let hash = 0;\n  for (let i = 0; i < userId.length; i++) hash = (hash * 31 + userId.charCodeAt(i)) | 0;\n  const key = AVATAR_TINT_KEYS[Math.abs(hash) % AVATAR_TINT_KEYS.length];\n  return (palette as unknown as Record<string, string>)[key] ?? palette.primary;\n}\n\n// ── Swatch ────────────────────────────────────────────────────────────────────\n\n/** Look up a named swatch; falls back to `palette.primary` if absent. */\nexport function swatch(theme: Theme, name: string): string {\n  return theme.swatches[name] ?? theme.colors.primary;\n}\n\n// ── Borders ───────────────────────────────────────────────────────────────────\n\n/** Derive a `borderColor` value for a \"paper\" (elevated surface) border. */\nexport function paperBorder(palette: Palette): string {\n  return palette.borderSubtle;\n}\n\n// ── Shadows ───────────────────────────────────────────────────────────────────\n\n/** Build a glow shadow token from a base color (used for focus rings, highlights). */\nexport function glowShadow(color: string, radius = 8, opacity = 0.4): ShadowToken {\n  return {\n    shadowColor: color,\n    shadowOffset: { width: 0, height: 0 },\n    shadowOpacity: opacity,\n    shadowRadius: radius,\n    elevation: 4,\n  };\n}\n\n// ── Focus ring ────────────────────────────────────────────────────────────────\n\n/** Style object for a keyboard-focus indicator (web + React Native). */\nexport function focusRingStyle(\n  palette: Palette,\n  width = 2,\n): {\n  borderWidth: number;\n  borderColor: string;\n  borderStyle: 'solid';\n} {\n  return { borderWidth: width, borderColor: palette.focus, borderStyle: 'solid' };\n}\n\n// ── Status color ──────────────────────────────────────────────────────────────\n\n/** Map a semantic status name to its palette color. */\nexport function statusColor(\n  palette: Palette,\n  status: 'success' | 'warning' | 'danger' | 'info' | string,\n  muted = false,\n): string {\n  if (muted) {\n    switch (status) {\n      case 'success': return palette.successMuted;\n      case 'warning': return palette.warningMuted;\n      case 'danger':  return palette.dangerMuted;\n      default:        return palette.infoMuted;\n    }\n  }\n  switch (status) {\n    case 'success': return palette.success;\n    case 'warning': return palette.warning;\n    case 'danger':  return palette.danger;\n    default:        return palette.info;\n  }\n}\n"],"mappings":";AAOA,OAAO,SAAS,eAAe,kBAAkB;AAGjD,IAAM,eAAe,cAA4B,IAAI;AAyB9C,SAAS,wBAAwB,EAAE,OAAO,SAAS,GAAiC;AACzF,SAAO,oCAAC,aAAa,UAAb,EAAsB,OAAO,SAAQ,QAAS;AACxD;AAOO,SAAS,qBAA4B;AAC1C,QAAM,QAAQ,WAAW,YAAY;AACrC,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO;AACT;;;AC1CO,SAAS,cACd,SACA,QACQ;AACR,UAAQ,QAAQ;AAAA,IACd,KAAK;AAAU,aAAO,QAAQ;AAAA,IAC9B,KAAK;AAAU,aAAO,QAAQ;AAAA,IAC9B,KAAK;AAAU,aAAO,QAAQ;AAAA,IAC9B;AAAe,aAAO,QAAQ;AAAA,EAChC;AACF;AAKO,SAAS,kBACd,SACA,OACQ;AACR,UAAQ,OAAO;AAAA,IACb,KAAK;AAAY,aAAO,QAAQ;AAAA,IAChC,KAAK;AAAY,aAAO,QAAQ;AAAA,IAChC;AAAiB,aAAO,QAAQ;AAAA,EAClC;AACF;AAIA,IAAM,mBAAmB;AAAA,EACvB;AAAA,EAAW;AAAA,EAAW;AAAA,EAAW;AAAA,EAAU;AAC7C;AAGO,SAAS,WAAW,SAAkB,QAAwB;AACnE,MAAI,OAAO;AACX,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,QAAQ,OAAO,KAAK,OAAO,WAAW,CAAC,IAAK;AACpF,QAAM,MAAM,iBAAiB,KAAK,IAAI,IAAI,IAAI,iBAAiB,MAAM;AACrE,SAAQ,QAA8C,GAAG,KAAK,QAAQ;AACxE;AAKO,SAAS,OAAO,OAAc,MAAsB;AACzD,SAAO,MAAM,SAAS,IAAI,KAAK,MAAM,OAAO;AAC9C;AAKO,SAAS,YAAY,SAA0B;AACpD,SAAO,QAAQ;AACjB;AAKO,SAAS,WAAW,OAAe,SAAS,GAAG,UAAU,KAAkB;AAChF,SAAO;AAAA,IACL,aAAa;AAAA,IACb,cAAc,EAAE,OAAO,GAAG,QAAQ,EAAE;AAAA,IACpC,eAAe;AAAA,IACf,cAAc;AAAA,IACd,WAAW;AAAA,EACb;AACF;AAKO,SAAS,eACd,SACA,QAAQ,GAKR;AACA,SAAO,EAAE,aAAa,OAAO,aAAa,QAAQ,OAAO,aAAa,QAAQ;AAChF;AAKO,SAAS,YACd,SACA,QACA,QAAQ,OACA;AACR,MAAI,OAAO;AACT,YAAQ,QAAQ;AAAA,MACd,KAAK;AAAW,eAAO,QAAQ;AAAA,MAC/B,KAAK;AAAW,eAAO,QAAQ;AAAA,MAC/B,KAAK;AAAW,eAAO,QAAQ;AAAA,MAC/B;AAAgB,eAAO,QAAQ;AAAA,IACjC;AAAA,EACF;AACA,UAAQ,QAAQ;AAAA,IACd,KAAK;AAAW,aAAO,QAAQ;AAAA,IAC/B,KAAK;AAAW,aAAO,QAAQ;AAAA,IAC/B,KAAK;AAAW,aAAO,QAAQ;AAAA,IAC/B;AAAgB,aAAO,QAAQ;AAAA,EACjC;AACF;","names":[]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@drakkar.software/octospaces-ui",
+  "version": "0.1.0",
+  "description": "Shared headless-themed UI primitives for OctoSpaces apps. Theme values are injected by the host app; this package ships only types + plumbing + primitives.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.75"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "~6.0.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/** @drakkar.software/octospaces-ui — public surface */
+
+// Theme plumbing — inject the host app's resolved Theme via provider, read it via hook.
+export { OctoSpacesThemeProvider, useOctoSpacesTheme } from './theme/provider.js';
+export type { OctoSpacesThemeProviderProps } from './theme/provider.js';
+
+// Theme types — host apps use these to type their resolved Theme object.
+export type {
+  ColorScheme,
+  Palette,
+  Theme,
+  Spacing,
+  Radii,
+  TypeScale,
+  Typography,
+  Fonts,
+  Easing,
+  MotionToken,
+  Motion,
+  ShadowToken,
+  Shadows,
+  Layout,
+  Opacity,
+  Swatches,
+  Layers,
+  LabelTracking,
+} from './theme/types.js';
+
+// Pure palette helpers — import and call with a Palette (or Theme) from useOctoSpacesTheme().
+export {
+  presenceColor,
+  verificationColor,
+  avatarTint,
+  swatch,
+  paperBorder,
+  glowShadow,
+  focusRingStyle,
+  statusColor,
+} from './theme/helpers.js';

package/src/theme/helpers.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from 'vitest';
+import type { Palette, Theme } from './types.js';
+import {
+  avatarTint,
+  focusRingStyle,
+  glowShadow,
+  paperBorder,
+  presenceColor,
+  statusColor,
+  swatch,
+  verificationColor,
+} from './helpers.js';
+
+const mockPalette: Palette = {
+  background: '#000',
+  surface: '#111',
+  surfaceElevated: '#222',
+  surfaceModal: '#333',
+  surfaceInput: '#444',
+  sidebar: '#555',
+  sidebarActive: '#666',
+  border: '#777',
+  borderSubtle: '#888',
+  borderStrong: '#999',
+  text: '#fff',
+  textSecondary: '#eee',
+  textTertiary: '#ddd',
+  textDisabled: '#ccc',
+  textInverse: '#000',
+  textOnPrimary: '#fff',
+  primary: '#6366f1',
+  primaryHover: '#4f46e5',
+  primaryMuted: '#312e81',
+  primarySubtle: '#1e1b4b',
+  success: '#22c55e',
+  successMuted: '#14532d',
+  warning: '#f59e0b',
+  warningMuted: '#78350f',
+  danger: '#ef4444',
+  dangerMuted: '#7f1d1d',
+  info: '#3b82f6',
+  infoMuted: '#1e3a5f',
+  presenceOnline: '#22c55e',
+  presenceAway: '#f59e0b',
+  presenceBusy: '#ef4444',
+  presenceOffline: '#6b7280',
+  verificationVerified: '#22c55e',
+  verificationPartial: '#f59e0b',
+  verificationNone: '#6b7280',
+  overlay: 'rgba(0,0,0,0.5)',
+  shadow: '#000',
+  focus: '#6366f1',
+  skeleton: '#333',
+  skeletonShimmer: '#444',
+  editorCanvas: '#1a1a2e',
+  tooltipBg: '#222',
+  onTooltip: '#fff',
+};
+
+const mockTheme: Theme = {
+  scheme: 'dark',
+  colors: mockPalette,
+  spacing: { '0': 0, '1': 4, '2': 8, '3': 12, '4': 16 },
+  radii: { sm: 4, md: 8, lg: 16, full: 9999 },
+  type: {},
+  fonts: {},
+  motion: {},
+  shadows: {},
+  layout: {},
+  opacity: { disabled: 0.5 },
+  swatches: { blue: '#3b82f6', green: '#22c55e', red: '#ef4444' },
+  layers: { modal: 100, tooltip: 200 },
+  easing: { standard: [0.4, 0, 0.2, 1] },
+  labelTracking: {},
+};
+
+describe('presenceColor', () => {
+  it('maps online → presenceOnline', () => {
+    expect(presenceColor(mockPalette, 'online')).toBe(mockPalette.presenceOnline);
+  });
+  it('maps away → presenceAway', () => {
+    expect(presenceColor(mockPalette, 'away')).toBe(mockPalette.presenceAway);
+  });
+  it('maps busy → presenceBusy', () => {
+    expect(presenceColor(mockPalette, 'busy')).toBe(mockPalette.presenceBusy);
+  });
+  it('falls back to offline for unknown status', () => {
+    expect(presenceColor(mockPalette, 'unknown')).toBe(mockPalette.presenceOffline);
+  });
+});
+
+describe('verificationColor', () => {
+  it('maps verified', () => {
+    expect(verificationColor(mockPalette, 'verified')).toBe(mockPalette.verificationVerified);
+  });
+  it('maps partial', () => {
+    expect(verificationColor(mockPalette, 'partial')).toBe(mockPalette.verificationPartial);
+  });
+  it('falls back to none', () => {
+    expect(verificationColor(mockPalette, 'unknown')).toBe(mockPalette.verificationNone);
+  });
+});
+
+describe('avatarTint', () => {
+  it('returns a string color', () => {
+    expect(typeof avatarTint(mockPalette, 'user123')).toBe('string');
+  });
+  it('is stable for the same userId', () => {
+    expect(avatarTint(mockPalette, 'alice')).toBe(avatarTint(mockPalette, 'alice'));
+  });
+  it('differs for different userIds', () => {
+    // Not guaranteed to differ, but very likely
+    const colors = new Set(['alice', 'bob', 'carol', 'dave', 'eve'].map(u => avatarTint(mockPalette, u)));
+    expect(colors.size).toBeGreaterThan(1);
+  });
+});
+
+describe('swatch', () => {
+  it('returns the named swatch', () => {
+    expect(swatch(mockTheme, 'blue')).toBe('#3b82f6');
+  });
+  it('falls back to primary for unknown swatch', () => {
+    expect(swatch(mockTheme, 'nonexistent')).toBe(mockPalette.primary);
+  });
+});
+
+describe('paperBorder', () => {
+  it('returns borderSubtle', () => {
+    expect(paperBorder(mockPalette)).toBe(mockPalette.borderSubtle);
+  });
+});
+
+describe('glowShadow', () => {
+  it('returns a shadow token with the given color', () => {
+    const shadow = glowShadow('#6366f1');
+    expect(shadow.shadowColor).toBe('#6366f1');
+    expect(typeof shadow.shadowRadius).toBe('number');
+  });
+  it('respects custom radius and opacity', () => {
+    const shadow = glowShadow('#fff', 12, 0.6);
+    expect(shadow.shadowRadius).toBe(12);
+    expect(shadow.shadowOpacity).toBe(0.6);
+  });
+});
+
+describe('focusRingStyle', () => {
+  it('returns an object with borderColor matching palette.focus', () => {
+    const ring = focusRingStyle(mockPalette);
+    expect(ring.borderColor).toBe(mockPalette.focus);
+    expect(ring.borderStyle).toBe('solid');
+    expect(ring.borderWidth).toBe(2);
+  });
+  it('respects custom width', () => {
+    expect(focusRingStyle(mockPalette, 3).borderWidth).toBe(3);
+  });
+});
+
+describe('statusColor', () => {
+  it('returns success color', () => {
+    expect(statusColor(mockPalette, 'success')).toBe(mockPalette.success);
+  });
+  it('returns muted variant when muted=true', () => {
+    expect(statusColor(mockPalette, 'danger', true)).toBe(mockPalette.dangerMuted);
+  });
+  it('falls back to info for unknown status', () => {
+    expect(statusColor(mockPalette, 'unknown')).toBe(mockPalette.info);
+  });
+});

package/src/theme/helpers.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure palette-helper functions over a {@link Palette}. No theme values live here —
+ * only functions that DERIVE from the injected palette (or from passed-in colors).
+ *
+ * Import these from `@drakkar.software/octospaces-ui` (re-exported by `src/index.ts`).
+ */
+import type { Palette, ShadowToken, Theme } from './types.js';
+
+// ── Presence ──────────────────────────────────────────────────────────────────
+
+/** Map a presence status string to the corresponding palette color. */
+export function presenceColor(
+  palette: Palette,
+  status: 'online' | 'away' | 'busy' | 'offline' | string,
+): string {
+  switch (status) {
+    case 'online': return palette.presenceOnline;
+    case 'away':   return palette.presenceAway;
+    case 'busy':   return palette.presenceBusy;
+    default:       return palette.presenceOffline;
+  }
+}
+
+// ── Verification ──────────────────────────────────────────────────────────────
+
+/** Map a verification level to the corresponding palette color. */
+export function verificationColor(
+  palette: Palette,
+  level: 'verified' | 'partial' | 'none' | string,
+): string {
+  switch (level) {
+    case 'verified': return palette.verificationVerified;
+    case 'partial':  return palette.verificationPartial;
+    default:         return palette.verificationNone;
+  }
+}
+
+// ── Avatar ────────────────────────────────────────────────────────────────────
+
+const AVATAR_TINT_KEYS = [
+  'primary', 'success', 'warning', 'danger', 'info',
+] as const;
+
+/** Stable avatar background tint derived from a userId string. */
+export function avatarTint(palette: Palette, userId: string): string {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) hash = (hash * 31 + userId.charCodeAt(i)) | 0;
+  const key = AVATAR_TINT_KEYS[Math.abs(hash) % AVATAR_TINT_KEYS.length];
+  return (palette as unknown as Record<string, string>)[key] ?? palette.primary;
+}
+
+// ── Swatch ────────────────────────────────────────────────────────────────────
+
+/** Look up a named swatch; falls back to `palette.primary` if absent. */
+export function swatch(theme: Theme, name: string): string {
+  return theme.swatches[name] ?? theme.colors.primary;
+}
+
+// ── Borders ───────────────────────────────────────────────────────────────────
+
+/** Derive a `borderColor` value for a "paper" (elevated surface) border. */
+export function paperBorder(palette: Palette): string {
+  return palette.borderSubtle;
+}
+
+// ── Shadows ───────────────────────────────────────────────────────────────────
+
+/** Build a glow shadow token from a base color (used for focus rings, highlights). */
+export function glowShadow(color: string, radius = 8, opacity = 0.4): ShadowToken {
+  return {
+    shadowColor: color,
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: opacity,
+    shadowRadius: radius,
+    elevation: 4,
+  };
+}
+
+// ── Focus ring ────────────────────────────────────────────────────────────────
+
+/** Style object for a keyboard-focus indicator (web + React Native). */
+export function focusRingStyle(
+  palette: Palette,
+  width = 2,
+): {
+  borderWidth: number;
+  borderColor: string;
+  borderStyle: 'solid';
+} {
+  return { borderWidth: width, borderColor: palette.focus, borderStyle: 'solid' };
+}
+
+// ── Status color ──────────────────────────────────────────────────────────────
+
+/** Map a semantic status name to its palette color. */
+export function statusColor(
+  palette: Palette,
+  status: 'success' | 'warning' | 'danger' | 'info' | string,
+  muted = false,
+): string {
+  if (muted) {
+    switch (status) {
+      case 'success': return palette.successMuted;
+      case 'warning': return palette.warningMuted;
+      case 'danger':  return palette.dangerMuted;
+      default:        return palette.infoMuted;
+    }
+  }
+  switch (status) {
+    case 'success': return palette.success;
+    case 'warning': return palette.warning;
+    case 'danger':  return palette.danger;
+    default:        return palette.info;
+  }
+}

package/src/theme/provider.tsx

@@ -0,0 +1,54 @@
+/**
+ * Theme injection plumbing — provider + hook.
+ *
+ * The package carries ZERO theme values. The host app builds a concrete {@link Theme}
+ * and wraps its tree in `<OctoSpacesThemeProvider theme={resolvedTheme}>`.
+ * All primitives then call `useOctoSpacesTheme()` to read the active theme.
+ */
+import React, { createContext, useContext } from 'react';
+import type { Theme } from './types.js';
+
+const ThemeContext = createContext<Theme | null>(null);
+
+export interface OctoSpacesThemeProviderProps {
+  theme: Theme;
+  children: React.ReactNode;
+}
+
+/**
+ * Wrap your root component with this provider to inject the resolved Theme into
+ * every primitive from `@drakkar.software/octospaces-ui`.
+ *
+ * @example
+ * ```tsx
+ * import { OctoSpacesThemeProvider } from '@drakkar.software/octospaces-ui';
+ * import { resolvedTheme } from '@/theme'; // your app's theme
+ *
+ * export default function App() {
+ *   return (
+ *     <OctoSpacesThemeProvider theme={resolvedTheme}>
+ *       <RootNavigator />
+ *     </OctoSpacesThemeProvider>
+ *   );
+ * }
+ * ```
+ */
+export function OctoSpacesThemeProvider({ theme, children }: OctoSpacesThemeProviderProps) {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+/**
+ * Read the active theme. Throws if called outside an `<OctoSpacesThemeProvider>` —
+ * this is intentional: a missing provider means primitives have no colors/spacing,
+ * so a hard failure with a clear message is better than a silent rendering bug.
+ */
+export function useOctoSpacesTheme(): Theme {
+  const theme = useContext(ThemeContext);
+  if (!theme) {
+    throw new Error(
+      '[octospaces-ui] useOctoSpacesTheme() called outside of <OctoSpacesThemeProvider>. ' +
+        'Wrap your root component with <OctoSpacesThemeProvider theme={…}>.',
+    );
+  }
+  return theme;
+}

package/src/theme/types.ts

@@ -0,0 +1,167 @@
+/**
+ * Theme contract for `@drakkar.software/octospaces-ui`.
+ *
+ * The package ships NO theme VALUES — only these type definitions. The host app
+ * constructs a concrete {@link Theme} object (with its own palette, tokens, and
+ * scheme logic) and passes it to `<OctoSpacesThemeProvider theme={…}>` at the root.
+ *
+ * The {@link Palette} interface is the SUPERSET of OctoChat + OctoVault so the UI
+ * primitives work correctly in both apps. Apps that don't use vault-specific keys
+ * (like `editorCanvas`) can safely set them to a sensible default.
+ */
+
+/** The active color scheme. Passed as part of `Theme.scheme`. */
+export type ColorScheme = 'light' | 'dark';
+
+/**
+ * Full color palette contract. OctoVault's palette is the superset. OctoChat apps
+ * add `editorCanvas`, `tooltipBg`, `onTooltip` as they migrate to the shared UI.
+ *
+ * All colors are CSS/RN color strings (hex, rgba, or named color tokens).
+ */
+export interface Palette {
+  // ── Background layers ─────────────────────────────────────────────────────
+  background: string;
+  surface: string;
+  surfaceElevated: string;
+  surfaceModal: string;
+  surfaceInput: string;
+  sidebar: string;
+  sidebarActive: string;
+
+  // ── Borders + dividers ────────────────────────────────────────────────────
+  border: string;
+  borderSubtle: string;
+  borderStrong: string;
+
+  // ── Text ─────────────────────────────────────────────────────────────────
+  text: string;
+  textSecondary: string;
+  textTertiary: string;
+  textDisabled: string;
+  textInverse: string;
+  textOnPrimary: string;
+
+  // ── Brand + interactive ───────────────────────────────────────────────────
+  primary: string;
+  primaryHover: string;
+  primaryMuted: string;
+  primarySubtle: string;
+
+  // ── Semantic ──────────────────────────────────────────────────────────────
+  success: string;
+  successMuted: string;
+  warning: string;
+  warningMuted: string;
+  danger: string;
+  dangerMuted: string;
+  info: string;
+  infoMuted: string;
+
+  // ── Presence + verification ───────────────────────────────────────────────
+  presenceOnline: string;
+  presenceAway: string;
+  presenceBusy: string;
+  presenceOffline: string;
+
+  verificationVerified: string;
+  verificationPartial: string;
+  verificationNone: string;
+
+  // ── Misc ──────────────────────────────────────────────────────────────────
+  overlay: string;
+  shadow: string;
+  focus: string;
+  skeleton: string;
+  skeletonShimmer: string;
+
+  // ── Vault-specific extras (superset) ─────────────────────────────────────
+  editorCanvas: string;
+  tooltipBg: string;
+  onTooltip: string;
+}
+
+/**
+ * Static spacing scale. Host app provides an object with numeric pixel values
+ * keyed by token name. E.g. `{ '0': 0, '1': 4, '2': 8, '3': 12, '4': 16, … }`.
+ */
+export type Spacing = Record<string, number>;
+
+/**
+ * Border-radius scale.
+ */
+export type Radii = Record<string, number | string>;
+
+/**
+ * Typography scale: font sizes, line heights, weights — keyed by variant name.
+ */
+export interface TypeScale {
+  size: number;
+  lineHeight: number;
+  weight?: string | number;
+  letterSpacing?: number;
+}
+export type Typography = Record<string, TypeScale>;
+
+/**
+ * Font family config. Keys are semantic names; values are font-family strings.
+ */
+export type Fonts = Record<string, string>;
+
+/** Easing curve definitions (e.g. for Reanimated `withTiming`). */
+export type Easing = Record<string, number[]>;
+
+/**
+ * Motion token: duration + easing pairs keyed by animation name.
+ */
+export interface MotionToken {
+  duration: number;
+  easing?: number[];
+}
+export type Motion = Record<string, MotionToken>;
+
+/** Shadow / elevation definitions. */
+export interface ShadowToken {
+  shadowColor?: string;
+  shadowOffset?: { width: number; height: number };
+  shadowOpacity?: number;
+  shadowRadius?: number;
+  elevation?: number;
+}
+export type Shadows = Record<string, ShadowToken>;
+
+/** Layout constants (screen margins, nav heights, etc.). */
+export type Layout = Record<string, number>;
+
+/** Opacity scale. */
+export type Opacity = Record<string, number>;
+
+/** Named color swatches (beyond the palette — brand accents, label colors). */
+export type Swatches = Record<string, string>;
+
+/** z-index layers. */
+export type Layers = Record<string, number>;
+
+/** Letter-spacing presets keyed by variant name. */
+export type LabelTracking = Record<string, number>;
+
+/**
+ * The complete Theme object the host app constructs and injects.
+ * All primitives in this package read ONLY from this injected Theme.
+ */
+export interface Theme {
+  scheme: ColorScheme;
+  colors: Palette;
+  spacing: Spacing;
+  radii: Radii;
+  type: Typography;
+  fonts: Fonts;
+  motion: Motion;
+  shadows: Shadows;
+  layout: Layout;
+  opacity: Opacity;
+  swatches: Swatches;
+  layers: Layers;
+  easing: Easing;
+  labelTracking: LabelTracking;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react-native",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  splitting: false,
+  sourcemap: true,
+  target: 'es2020',
+  external: ['react', 'react-native'],
+});

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: false,
+    include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
+  },
+});