@oddsmith/ui 1.0.5 → 1.0.6

package/README.md

@@ -1,7 +1,11 @@
-# @oddsmith/ui
+# Casino Leaderboard Component
 
-Brandable **Lit web components** built and published from this package.
+Deploy a fully brandable casino leaderboard, ready to match your brand. Live rankings, prize tiers, and campaign stats. Your data, our UI.
 
-**Current focus:** `os-leaderboard-casino` — a config-driven casino leaderboard (`<os-leaderboard-casino>`). Older component families live under `src/components/_archive/` for reference only.
+```ts
+import { OsLeaderboardCasino } from '@oddsmith/ui/os-leaderboard-casino';
+```
 
-**Integration status:** The public API is stabilizing. This README describes how the repo works today for internal development. Full client integration docs will follow separately.
+There is no root `@oddsmith/ui` entry. Pro is `@oddsmith/ui/os-leaderboard-casino-pro`.
+
+[Integration docs](https://app.notion.com/p/Client-integration-3c9437e762d68075b87ff9fd358678dd)

package/dist/.shared/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared runtime for os-* components. Import via subpath aliases:
+ * `@oddsmith/lib/*`, `@oddsmith/theme-engine`, `@oddsmith/labels-engine`.
+ */
+export {};

package/dist/.shared/labels-engine/engine.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic labels bag — any component's `labels.json` shape.
+ * Component-specific types (e.g. LeaderboardLabels) live next to that component.
+ */
+export type LabelsMap = Record<string, string>;
+/**
+ * Stamps a labels bag on a host and can reverse that stamp.
+ * Nested objects are flattened to dotted keys (`hero.pool`).
+ * {@link LabelsEngine.get} walks out of shadow roots to find that host.
+ */
+export declare class LabelsEngine {
+    private static readonly labels;
+    apply(host: object, labels: object): void;
+    clear(host: object): void;
+    /**
+     * Resolves one label key from the stamped host, or from a descendant
+     * (walks parent elements and shadow hosts).
+     * Missing or empty values return `'n/a'`.
+     */
+    static get(from: object, key: string): string;
+    private static resolveHost;
+}

package/dist/.shared/labels-engine/engine.ts

@@ -0,0 +1,70 @@
+/**
+ * Generic labels bag — any component's `labels.json` shape.
+ * Component-specific types (e.g. LeaderboardLabels) live next to that component.
+ */
+export type LabelsMap = Record<string, string>;
+
+function flattenLabels(
+  value: unknown,
+  prefix = '',
+  out: LabelsMap = {},
+): LabelsMap {
+  if (typeof value === 'string') {
+    if (prefix) out[prefix] = value;
+    return out;
+  }
+  if (value != null && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      flattenLabels(child, path, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Stamps a labels bag on a host and can reverse that stamp.
+ * Nested objects are flattened to dotted keys (`hero.pool`).
+ * {@link LabelsEngine.get} walks out of shadow roots to find that host.
+ */
+export class LabelsEngine {
+  private static readonly labels = new WeakMap<object, LabelsMap>();
+
+  apply(host: object, labels: object): void {
+    LabelsEngine.labels.set(host, flattenLabels(labels));
+  }
+
+  clear(host: object): void {
+    LabelsEngine.labels.delete(host);
+  }
+
+  /**
+   * Resolves one label key from the stamped host, or from a descendant
+   * (walks parent elements and shadow hosts).
+   * Missing or empty values return `'n/a'`.
+   */
+  static get(from: object, key: string): string {
+    const host = LabelsEngine.resolveHost(from);
+    const value = host != null ? LabelsEngine.labels.get(host)?.[key] : undefined;
+    return value != null && value !== '' ? value : 'n/a';
+  }
+
+  private static resolveHost(from: object): object | null {
+    if (LabelsEngine.labels.has(from)) return from;
+    if (!(from instanceof Node)) return null;
+
+    let node: Node | null = from;
+    while (node) {
+      if (node instanceof Element && LabelsEngine.labels.has(node)) {
+        return node;
+      }
+      if (node instanceof Element && node.parentElement) {
+        node = node.parentElement;
+        continue;
+      }
+      const root = node.getRootNode();
+      node = root instanceof ShadowRoot ? root.host : null;
+    }
+    return null;
+  }
+}

package/dist/.shared/labels-engine/index.d.ts

@@ -0,0 +1 @@
+export { LabelsEngine, type LabelsMap } from './engine.js';

package/dist/.shared/labels-engine/index.ts

@@ -0,0 +1 @@
+export { LabelsEngine, type LabelsMap } from './engine.js';

package/dist/.shared/lib/lit/component.ts

@@ -0,0 +1,10 @@
+import { customElement } from './safe-custom-element.js';
+
+export interface ComponentOptions {
+  selector: string;
+}
+
+/** Angular-style `@Component` — registers a Lit class as a custom element. */
+export function Component(options: ComponentOptions) {
+  return customElement(options.selector);
+}

package/dist/.shared/lib/lit/safe-custom-element.ts

@@ -0,0 +1,12 @@
+/**
+ * Registers a custom element only if the tag is not already in the registry.
+ * Use instead of Lit's `@customElement` when HMR or duplicate bundles are possible.
+ */
+export function customElement(tag: string) {
+  return <T extends CustomElementConstructor>(cls: T): T => {
+    if (!customElements.get(tag)) {
+      customElements.define(tag, cls);
+    }
+    return cls;
+  };
+}

package/dist/.shared/lib/lit/scss.ts

@@ -0,0 +1,6 @@
+import { unsafeCSS, type CSSResult } from '@lit/reactive-element/css-tag.js';
+
+/** Compiled SCSS string → adoptable shadow-root stylesheet. */
+export function scss(stylesheet: string): CSSResult {
+  return unsafeCSS(stylesheet);
+}

package/dist/{shared/lib/lit/template.d.ts → .shared/lib/lit/template.ts}

@@ -1,3 +1,4 @@
-import { nothing, TemplateResult } from 'lit';
+import { nothing, type TemplateResult } from 'lit';
+
 /** Lit template slot — real fragment or `nothing` when a section is omitted. */
 export type LitTemplate = TemplateResult | typeof nothing;

package/dist/.shared/theme-engine/animation.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs `apply` while a short-lived transition class is on `nodes`.
+ * Skipped when `animate` is false or the user prefers reduced motion.
+ */
+export declare function withThemeTransition(nodes: HTMLElement[], animate: boolean, apply: () => void): void;

package/dist/.shared/theme-engine/animation.ts

@@ -0,0 +1,40 @@
+const THEME_TRANSITION_CLASS = 'os-theme-transition';
+const THEME_TRANSITION_MS = 500;
+const THEME_TRANSITION_DELAY_MS = 500;
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof matchMedia !== 'undefined' &&
+    matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/**
+ * Runs `apply` while a short-lived transition class is on `nodes`.
+ * Skipped when `animate` is false or the user prefers reduced motion.
+ */
+export function withThemeTransition(
+  nodes: HTMLElement[],
+  animate: boolean,
+  apply: () => void,
+): void {
+  const runAnimation = animate && !prefersReducedMotion();
+
+  if (runAnimation) {
+    for (const node of nodes) {
+      node.classList.add(THEME_TRANSITION_CLASS);
+    }
+    void nodes[0]?.offsetHeight;
+  }
+
+  apply();
+
+  if (runAnimation) {
+    const totalMs = THEME_TRANSITION_DELAY_MS + THEME_TRANSITION_MS + 80;
+    window.setTimeout(() => {
+      for (const node of nodes) {
+        node.classList.remove(THEME_TRANSITION_CLASS);
+      }
+    }, totalMs);
+  }
+}

package/dist/.shared/theme-engine/default-theme.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Palette bag. Operator chrome colors — not campaign content.
+ *
+ * Host `.theme` is mixed onto glam {@link DEFAULT_THEME} per key.
+ * `background` and `surface` are CSS backgrounds (solid color or gradient).
+ * `fontDisplay` / `fontBody` / `fontMono` are CSS `font-family` stacks.
+ * The component does not load font files — the host must.
+ */
+export type LeaderboardTheme = {
+    background: string;
+    surface: string;
+    text: string;
+    textMuted: string;
+    primary: string;
+    secondary: string;
+    success: string;
+    danger: string;
+    borderRadius: string;
+    fontDisplay: string;
+    fontBody: string;
+    fontMono: string;
+};
+/** Glam palette used when the host omits `.theme`. */
+export declare const DEFAULT_THEME: LeaderboardTheme;

package/dist/.shared/theme-engine/default-theme.ts

@@ -0,0 +1,38 @@
+/**
+ * Palette bag. Operator chrome colors — not campaign content.
+ *
+ * Host `.theme` is mixed onto glam {@link DEFAULT_THEME} per key.
+ * `background` and `surface` are CSS backgrounds (solid color or gradient).
+ * `fontDisplay` / `fontBody` / `fontMono` are CSS `font-family` stacks.
+ * The component does not load font files — the host must.
+ */
+export type LeaderboardTheme = {
+  background: string;
+  surface: string;
+  text: string;
+  textMuted: string;
+  primary: string;
+  secondary: string;
+  success: string;
+  danger: string;
+  borderRadius: string;
+  fontDisplay: string;
+  fontBody: string;
+  fontMono: string;
+};
+
+/** Glam palette used when the host omits `.theme`. */
+export const DEFAULT_THEME: LeaderboardTheme = {
+  background: '#181622',
+  surface: 'rgba(26, 19, 42, 0.78)',
+  text: '#f7f3ff',
+  textMuted: '#ab9fce',
+  primary: '#f5c451',
+  secondary: '#9d6bff',
+  success: '#41e6a5',
+  danger: '#ff5d7c',
+  borderRadius: '20px',
+  fontDisplay: "'Sora', system-ui, sans-serif",
+  fontBody: "'Inter', system-ui, sans-serif",
+  fontMono: "ui-monospace, 'JetBrains Mono', monospace",
+};

package/dist/.shared/theme-engine/engine.d.ts

@@ -0,0 +1,22 @@
+import { LeaderboardTheme } from './default-theme.js';
+export type ThemeEngineOptions = {
+    /** Animate color token changes on the host. */
+    animate?: boolean;
+    /** Prefix for mix/validation console.error. */
+    logPrefix?: string;
+};
+/**
+ * Mixes a host palette onto {@link DEFAULT_THEME} and stamps the 12 keys
+ * as CSS vars on the host.
+ */
+export declare class ThemeEngine {
+    private host;
+    private stamped;
+    apply(host: HTMLElement, input?: Partial<LeaderboardTheme> | null, options?: ThemeEngineOptions): void;
+    clear(host: HTMLElement, options?: ThemeEngineOptions): void;
+    private unstamp;
+    private resolveTheme;
+    private pickCss;
+    private pickFont;
+    private cssSupports;
+}

package/dist/.shared/theme-engine/engine.ts

@@ -0,0 +1,151 @@
+import { withThemeTransition } from './animation.js';
+import { DEFAULT_THEME, type LeaderboardTheme } from './default-theme.js';
+
+export type ThemeEngineOptions = {
+  /** Animate color token changes on the host. */
+  animate?: boolean;
+  /** Prefix for mix/validation console.error. */
+  logPrefix?: string;
+};
+
+/** CSS custom properties stamped from the 12 host keys. */
+const THEME_CSS_VARS: Record<keyof LeaderboardTheme, `--${string}`> = {
+  background: '--background',
+  surface: '--surface',
+  text: '--text',
+  textMuted: '--text-muted',
+  primary: '--primary',
+  secondary: '--secondary',
+  success: '--success',
+  danger: '--danger',
+  borderRadius: '--border-radius',
+  fontDisplay: '--font-display',
+  fontBody: '--font-body',
+  fontMono: '--font-mono',
+};
+
+const CSS_PROPERTY: Record<
+  Exclude<keyof LeaderboardTheme, 'fontDisplay' | 'fontBody' | 'fontMono'>,
+  string
+> = {
+  background: 'background',
+  surface: 'background',
+  text: 'color',
+  textMuted: 'color',
+  primary: 'color',
+  secondary: 'color',
+  success: 'color',
+  danger: 'color',
+  borderRadius: 'border-radius',
+};
+
+/**
+ * Mixes a host palette onto {@link DEFAULT_THEME} and stamps the 12 keys
+ * as CSS vars on the host.
+ */
+export class ThemeEngine {
+  private host: HTMLElement | null = null;
+  private stamped: LeaderboardTheme | null = null;
+
+  apply(
+    host: HTMLElement,
+    input?: Partial<LeaderboardTheme> | null,
+    options: ThemeEngineOptions = {},
+  ): void {
+    const theme = this.resolveTheme(input, options.logPrefix);
+    withThemeTransition([host], options.animate === true, () => {
+      this.unstamp();
+      for (const key of Object.keys(THEME_CSS_VARS) as (keyof LeaderboardTheme)[]) {
+        host.style.setProperty(THEME_CSS_VARS[key], theme[key]);
+      }
+      this.host = host;
+      this.stamped = theme;
+    });
+  }
+
+  clear(host: HTMLElement, options: ThemeEngineOptions = {}): void {
+    withThemeTransition([host], options.animate === true, () => {
+      this.unstamp(host);
+      this.host = null;
+      this.stamped = null;
+    });
+  }
+
+  private unstamp(host: HTMLElement | null = this.host): void {
+    if (host == null || this.stamped == null) return;
+    for (const varName of Object.values(THEME_CSS_VARS)) {
+      host.style.removeProperty(varName);
+    }
+  }
+
+  private resolveTheme(
+    input?: Partial<LeaderboardTheme> | null,
+    logPrefix = '[os-leaderboard-casino]',
+  ): LeaderboardTheme {
+    return {
+      background: this.pickCss(input, 'background', logPrefix),
+      surface: this.pickCss(input, 'surface', logPrefix),
+      text: this.pickCss(input, 'text', logPrefix),
+      textMuted: this.pickCss(input, 'textMuted', logPrefix),
+      primary: this.pickCss(input, 'primary', logPrefix),
+      secondary: this.pickCss(input, 'secondary', logPrefix),
+      success: this.pickCss(input, 'success', logPrefix),
+      danger: this.pickCss(input, 'danger', logPrefix),
+      borderRadius: this.pickCss(input, 'borderRadius', logPrefix),
+      fontDisplay: this.pickFont(input, 'fontDisplay', logPrefix),
+      fontBody: this.pickFont(input, 'fontBody', logPrefix),
+      fontMono: this.pickFont(input, 'fontMono', logPrefix),
+    };
+  }
+
+  private pickCss(
+    input: Partial<LeaderboardTheme> | null | undefined,
+    key: keyof typeof CSS_PROPERTY,
+    logPrefix: string,
+  ): string {
+    const fallback = DEFAULT_THEME[key];
+    if (input == null || !Object.prototype.hasOwnProperty.call(input, key)) {
+      return fallback;
+    }
+    const raw = input[key];
+    if (typeof raw !== 'string' || raw.trim() === '') {
+      console.error(
+        `${logPrefix} theme.${key} is missing or empty; using default.`,
+      );
+      return fallback;
+    }
+    if (!this.cssSupports(CSS_PROPERTY[key], raw)) {
+      console.error(
+        `${logPrefix} theme.${key} is invalid CSS (${JSON.stringify(raw)}); using default.`,
+      );
+      return fallback;
+    }
+    return raw;
+  }
+
+  private pickFont(
+    input: Partial<LeaderboardTheme> | null | undefined,
+    key: 'fontDisplay' | 'fontBody' | 'fontMono',
+    logPrefix: string,
+  ): string {
+    const fallback = DEFAULT_THEME[key];
+    if (input == null || !Object.prototype.hasOwnProperty.call(input, key)) {
+      return fallback;
+    }
+    const raw = input[key];
+    if (typeof raw !== 'string' || raw.trim() === '') {
+      console.error(
+        `${logPrefix} theme.${key} is missing or empty; using default.`,
+      );
+      return fallback;
+    }
+    return raw;
+  }
+
+  private cssSupports(property: string, value: string): boolean {
+    if (typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+      return value.trim() !== '';
+    }
+    return CSS.supports(property, value);
+  }
+}

package/dist/.shared/theme-engine/index.d.ts

@@ -0,0 +1,2 @@
+export { ThemeEngine, type ThemeEngineOptions, } from './engine.js';
+export { DEFAULT_THEME, type LeaderboardTheme, } from './default-theme.js';

package/dist/.shared/theme-engine/index.ts

@@ -0,0 +1,8 @@
+export {
+  ThemeEngine,
+  type ThemeEngineOptions,
+} from './engine.js';
+export {
+  DEFAULT_THEME,
+  type LeaderboardTheme,
+} from './default-theme.js';