@decentrys/ui-sdk 0.1.0

package/src/theme.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Theming has to be genuinely customisable, which means two things have to
+ * stay true and neither is obvious from reading either file alone:
+ *
+ *  - Every value the stylesheet paints with is a token an integrator can
+ *    override. A colour hard-coded into a rule is a colour they cannot change,
+ *    and they will find that out inside their own wallet.
+ *  - No token exists only in the dark-mode block. One that did would be
+ *    undefined in light mode and silently paint nothing.
+ *
+ * Both are checked against the stylesheet text itself, so the token API and
+ * the CSS cannot drift apart without a test failing.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { THEME_TOKENS, themeStyle, toneBgVar, toneVar, type DecentrysTheme } from './theme';
+import { DECENTRYS_UI_CSS } from './styles';
+
+function block(selector: string): string {
+  const start = DECENTRYS_UI_CSS.indexOf(selector);
+  expect(start, `${selector} missing from the stylesheet`).toBeGreaterThan(-1);
+  const open = DECENTRYS_UI_CSS.indexOf('{', start);
+  const close = DECENTRYS_UI_CSS.indexOf('}', open);
+  return DECENTRYS_UI_CSS.slice(open, close);
+}
+
+function definedTokens(css: string): Set<string> {
+  return new Set([...css.matchAll(/--dcy-([a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+}
+
+describe('themeStyle', () => {
+  it('emits custom properties an integrator can override the defaults with', () => {
+    const style = themeStyle({ surface: '#0b0d10', text: '#e8ebef' }) as Record<string, string>;
+    expect(style['--dcy-surface']).toBe('#0b0d10');
+    expect(style['--dcy-text']).toBe('#e8ebef');
+  });
+
+  it('leaves the caller’s own style properties in place', () => {
+    const style = themeStyle({ radius: '0px' }, { marginTop: 8 }) as Record<string, unknown>;
+    expect(style.marginTop).toBe(8);
+    expect(style['--dcy-radius']).toBe('0px');
+  });
+
+  it('returns the base style untouched when there is no theme', () => {
+    expect(themeStyle(undefined, { marginTop: 8 })).toEqual({ marginTop: 8 });
+    expect(themeStyle(undefined)).toBeUndefined();
+  });
+
+  it('ignores empty values rather than blanking a token', () => {
+    const style = themeStyle({ surface: '' } as DecentrysTheme) as Record<string, string>;
+    expect('--dcy-surface' in style).toBe(false);
+  });
+
+  it('references tones through variables, so a palette swap reaches everything', () => {
+    expect(toneVar('critical')).toBe('var(--dcy-tone-critical)');
+    expect(toneBgVar('capability')).toBe('var(--dcy-tone-capability-bg)');
+  });
+});
+
+describe('the stylesheet and the token API', () => {
+  it('declares exactly the tokens the theme type exposes', () => {
+    const declared = definedTokens(block('.dcy {'));
+    expect([...declared].sort()).toEqual([...THEME_TOKENS].sort());
+  });
+
+  it('defines no token that exists only in dark mode', () => {
+    const light = definedTokens(block('.dcy {'));
+    const darkStart = DECENTRYS_UI_CSS.indexOf('@media (prefers-color-scheme: dark)');
+    const dark = definedTokens(DECENTRYS_UI_CSS.slice(darkStart, DECENTRYS_UI_CSS.indexOf('}', DECENTRYS_UI_CSS.indexOf('{', DECENTRYS_UI_CSS.indexOf('.dcy {', darkStart)))));
+    for (const token of dark) expect(light.has(token), `--dcy-${token}`).toBe(true);
+    expect(dark.size).toBeGreaterThan(0);
+  });
+
+  it('gives every tone both a foreground and a background token', () => {
+    const tones = [
+      'neutral', 'info', 'caution', 'elevated', 'high', 'critical',
+      'fact', 'capability', 'unknown', 'inactive',
+    ];
+    for (const tone of tones) {
+      expect(THEME_TOKENS).toContain(`tone-${tone}`);
+      expect(THEME_TOKENS).toContain(`tone-${tone}-bg`);
+      expect(DECENTRYS_UI_CSS).toContain(`[data-dcy-tone="${tone}"]`);
+    }
+  });
+
+  it('carries a visible focus style, since these ship into other people’s apps', () => {
+    expect(DECENTRYS_UI_CSS).toContain(':focus-visible');
+    expect(DECENTRYS_UI_CSS).toContain('outline: 2px solid var(--dcy-focus)');
+  });
+
+  it('separates the kinds by rule style as well as by colour', () => {
+    expect(DECENTRYS_UI_CSS).toContain('[data-dcy-rule="solid"]');
+    expect(DECENTRYS_UI_CSS).toContain('[data-dcy-rule="dashed"]');
+    expect(DECENTRYS_UI_CSS).toContain('[data-dcy-rule="dotted"]');
+  });
+
+  it('brings no styling dependency along with it', () => {
+    // These components land inside somebody else's build. A @import, a
+    // Tailwind directive or a webfont fetch would be a cost they did not agree
+    // to, and a CSP violation in half the wallets that embed this.
+    expect(DECENTRYS_UI_CSS).not.toContain('@import');
+    expect(DECENTRYS_UI_CSS).not.toContain('@tailwind');
+    expect(DECENTRYS_UI_CSS).not.toContain('url(');
+  });
+});

package/src/theme.ts

@@ -0,0 +1,117 @@
+/**
+ * Theming.
+ *
+ * These components ship into other people's wallets, so two things are true at
+ * once: they must look like something out of the box, and they must never
+ * force a Decentrys palette onto an application that has its own. Every visual
+ * value is therefore a CSS custom property with a default, and there are three
+ * escalating ways to override it:
+ *
+ *  1. `theme` — a token map applied inline on the component's own root, which
+ *     beats every stylesheet rule including the dark-mode defaults.
+ *  2. `className` — the integrator's own class on the same root, for anything
+ *     tokens do not reach.
+ *  3. `data-dcy-*` attributes, present on every meaningful element
+ *     (`data-dcy-level`, `data-dcy-kind`, `data-dcy-tone`), so an integrator
+ *     can target our internals from their own stylesheet without us exporting
+ *     a class-name contract we would then have to keep.
+ *
+ * No styling dependency is used or needed. Adding Tailwind or a CSS-in-JS
+ * runtime to a package that lands inside someone else's build is a cost they
+ * did not agree to.
+ */
+
+import type { CSSProperties } from 'react';
+
+/**
+ * Tones.
+ *
+ * Deliberately *not* a severity scale with `safe` at one end. `fact`,
+ * `capability` and `unknown` are separate tone families from the risk tones,
+ * because a fact and a threat signal rendering in the same colour is the exact
+ * failure this product exists to prevent — and `inactive` exists so a stale or
+ * low-confidence signal, which did not affect the assessment, cannot be shown
+ * in the colour of one that did.
+ */
+export type Tone =
+  | 'neutral'
+  | 'info'
+  | 'caution'
+  | 'elevated'
+  | 'high'
+  | 'critical'
+  | 'fact'
+  | 'capability'
+  | 'unknown'
+  | 'inactive';
+
+export const THEME_TOKENS = [
+  'font',
+  'font-mono',
+  'radius',
+  'gap',
+  'surface',
+  'surface-raised',
+  'border',
+  'text',
+  'text-muted',
+  'text-faint',
+  'focus',
+  'tone-neutral',
+  'tone-neutral-bg',
+  'tone-info',
+  'tone-info-bg',
+  'tone-caution',
+  'tone-caution-bg',
+  'tone-elevated',
+  'tone-elevated-bg',
+  'tone-high',
+  'tone-high-bg',
+  'tone-critical',
+  'tone-critical-bg',
+  'tone-fact',
+  'tone-fact-bg',
+  'tone-capability',
+  'tone-capability-bg',
+  'tone-unknown',
+  'tone-unknown-bg',
+  'tone-inactive',
+  'tone-inactive-bg',
+] as const;
+
+export type ThemeToken = (typeof THEME_TOKENS)[number];
+
+/** A partial map of token → CSS value. Anything omitted keeps its default. */
+export type DecentrysTheme = Partial<Record<ThemeToken, string>>;
+
+/**
+ * Turn a theme into inline custom properties.
+ *
+ * Inline custom properties win over the stylesheet's defaults *and* over the
+ * `prefers-color-scheme` block, which is the behaviour an integrator with a
+ * fixed brand palette needs — otherwise their light theme would flip to our
+ * dark one on a user's OS setting.
+ */
+export function themeStyle(
+  theme?: DecentrysTheme,
+  base?: CSSProperties,
+): CSSProperties | undefined {
+  if (!theme) return base;
+  const style: Record<string, string> = {};
+  for (const [token, value] of Object.entries(theme)) {
+    if (typeof value === 'string' && value.length > 0) style[`--dcy-${token}`] = value;
+  }
+  // Custom properties are not part of the CSSProperties index signature; the
+  // cast is the standard, and only, way to express them in React's types.
+  return { ...(base ?? {}), ...style } as CSSProperties;
+}
+
+/** The CSS variable reference for a tone's foreground, e.g. for a border. */
+export function toneVar(tone: Tone): string {
+  return `var(--dcy-tone-${tone})`;
+}
+
+/** The CSS variable reference for a tone's background wash. */
+export function toneBgVar(tone: Tone): string {
+  return `var(--dcy-tone-${tone}-bg)`;
+}