@lcars-gui/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aarondnas
+
+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,19 @@
-# Temporary Holding Version
+# @lcars-gui/core
 
-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.
+Shared foundation of the lcars-gui faction packages. You usually don't need this package directly –
+it is installed along with [`@lcars-gui/federation`](https://www.npmjs.com/package/@lcars-gui/federation) and
+[`@lcars-gui/romulus`](https://www.npmjs.com/package/@lcars-gui/romulus).
+
+## Contents
+
+| Export                      | Purpose                                                                 |
+|-----------------------------|-------------------------------------------------------------------------|
+| `createLcarsSound()`        | Synthesized interface sounds via the Web Audio API (no audio files)     |
+| `initBehaviors()`           | Behavior for plain HTML/JS: toggles, tabs, keypads, sounds              |
+| `seededRandom()`, `cx()`    | Small helpers                                                           |
+| `@lcars-gui/core/react`     | `SoundProvider`, `useLcarsSound` – one sound context for all factions   |
+| `@lcars-gui/core/build`     | `buildCss()` – generates a faction's CSS from tokens and component CSS  |
+
+## License
+
+MIT

package/build/css.js

@@ -0,0 +1,123 @@
+// Generates a faction package's CSS from its tokens and component styles.
+// Expected folder structure (relative to `root`):
+//
+//   tokens/base.json          sizes, font sizes, base colors …  → :root variables
+//   tokens/themes/<name>.json color palette per theme           → [data-theme="<name>"]
+//   tokens/alerts/<name>.json color palette per alert level     → [data-alert="<name>"]
+//   css/*.css                 component styles (sorted by file name)
+//   themes/<name>/theme.css   theme extras (optional)           → dist/themes/<name>.css
+//   fonts/                    fonts (optional)                  → dist/fonts/
+//
+// Output: dist/ui.css (+ dist/themes/*.css, dist/fonts/).
+import fs from "fs";
+import path from "path";
+
+// Helper function: camelCase → kebab-case
+const kebab = (str) =>
+  str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+// All JSON files in a folder as { name: content }
+function readJsonDir(dir) {
+  if (!fs.existsSync(dir)) return {};
+  return Object.fromEntries(
+    fs
+      .readdirSync(dir)
+      .filter((file) => file.endsWith(".json"))
+      .sort()
+      .map((file) => [path.basename(file, ".json"), readJson(path.join(dir, file))])
+  );
+}
+
+// Generate css-variables from all base tokens
+function generateCssVars(baseTokens, vars) {
+  let css = "";
+  for (const [group, values] of Object.entries(baseTokens)) {
+    for (const [key, value] of Object.entries(values)) {
+      css += `  --${vars}${group}-${kebab(key)}: ${value};\n`;
+    }
+  }
+  return css;
+}
+
+// Palette → --colors-* variables. Missing hover colors are derived.
+function generatePalette(palette, vars) {
+  let css = "";
+  for (const [key, value] of Object.entries(palette)) {
+    if (key.endsWith("hover")) continue;
+    const hover = palette[`${key}hover`] ?? `color-mix(in srgb, ${value} 65%, white)`;
+    css += `  --${vars}colors-${key}: ${value};\n`;
+    css += `  --${vars}colors-${key}hover: ${hover};\n`;
+  }
+  return css;
+}
+
+// Colors: data-color="n" sets --<prefix>-bg / --<prefix>-bg-hover (inherited by children)
+function generateColorStyles(palette, prefix, vars) {
+  let css = "/* Colors */\n";
+  for (let i = 1; palette[`color${i}`]; i++) {
+    css += `[data-color="${i}"] { --${prefix}-bg: var(--${vars}colors-color${i}); --${prefix}-bg-hover: var(--${vars}colors-color${i}hover); }\n`;
+  }
+  return css + "\n";
+}
+
+function generatePaletteBlocks(palettes, attribute, vars) {
+  return Object.entries(palettes)
+    .map(([name, palette]) => `[${attribute}="${name}"] {\n${generatePalette(palette, vars)}}\n`)
+    .join("");
+}
+
+// Component styles: css/*.css in file name order
+function readComponentStyles(cssDir) {
+  return fs
+    .readdirSync(cssDir)
+    .filter((file) => file.endsWith(".css"))
+    .sort()
+    .map((file) => `/* ==================== ${file} ==================== */\n\n` + fs.readFileSync(path.join(cssDir, file), "utf8"))
+    .join("\n");
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.root          the faction's package folder
+ * @param {string} options.defaultTheme  theme whose palette is applied to :root
+ * @param {string} [options.prefix]      prefix of CSS classes/variables (e.g. "lcar")
+ * @param {string} [options.varPrefix]   prefix of token variables (e.g. "rom-" → --rom-colors-color1),
+ *                                       so several factions can coexist on one page
+ */
+export function buildCss({ root, defaultTheme, prefix = "lcar", varPrefix = "" }) {
+  const distDir = path.join(root, "dist");
+  const base = readJson(path.join(root, "tokens/base.json"));
+  const themes = readJsonDir(path.join(root, "tokens/themes"));
+  const alerts = readJsonDir(path.join(root, "tokens/alerts"));
+
+  const defaultPalette = themes[defaultTheme];
+  if (!defaultPalette) throw new Error(`Theme "${defaultTheme}" is missing in tokens/themes/`);
+
+  const finalCss =
+    "/* AUTO-GENERATED FROM tokens/ + css/*.css — DO NOT EDIT */\n\n" +
+    `:root {\n${generateCssVars(base, varPrefix)}${generatePalette(defaultPalette, varPrefix)}}\n\n` +
+    generateColorStyles(defaultPalette, prefix, varPrefix) +
+    "/* Themes */\n" + generatePaletteBlocks(themes, "data-theme", varPrefix) + "\n" +
+    "/* Alert palettes */\n" + generatePaletteBlocks(alerts, "data-alert", varPrefix) + "\n" +
+    readComponentStyles(path.join(root, "css"));
+
+  fs.mkdirSync(distDir, { recursive: true });
+  fs.writeFileSync(path.join(distDir, "ui.css"), finalCss);
+
+  // Theme extras
+  const themesDir = path.join(root, "themes");
+  if (fs.existsSync(themesDir)) {
+    fs.mkdirSync(path.join(distDir, "themes"), { recursive: true });
+    for (const name of fs.readdirSync(themesDir)) {
+      const file = path.join(themesDir, name, "theme.css");
+      if (fs.existsSync(file)) fs.copyFileSync(file, path.join(distDir, "themes", `${name}.css`));
+    }
+  }
+
+  const fontsDir = path.join(root, "fonts");
+  if (fs.existsSync(fontsDir)) {
+    fs.cpSync(fontsDir, path.join(distDir, "fonts"), { recursive: true });
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+type LcarsSoundKind = "beep" | "confirm" | "deny" | "alert";
+/** [frequency in Hz, duration in ms] for each tone of a pattern */
+type LcarsSoundPatterns = Record<LcarsSoundKind, [number, number][]>;
+interface LcarsSoundOptions {
+    /** Sound patterns per kind (default: Federation sounds) */
+    patterns?: LcarsSoundPatterns;
+    /** Oscillator waveform (default: "sine") */
+    wave?: OscillatorType;
+}
+interface LcarsSound {
+    play(kind?: LcarsSoundKind): void;
+}
+declare function createLcarsSound(volume?: number, { patterns, wave }?: LcarsSoundOptions): LcarsSound;
+
+interface BehaviorSelectors {
+    /** Elements that play a sound when clicked (buttons, tabs) */
+    control: string;
+    /** Keypad container */
+    keypad: string;
+    /** Key inside a keypad */
+    keypadKey: string;
+    /** Display inside a keypad */
+    keypadDisplay: string;
+}
+interface InitBehaviorsOptions {
+    /** Area to wire up (default: document) */
+    root?: Document | HTMLElement;
+    /** Enable interface sounds from the start (later: setSound) */
+    sound?: boolean;
+    volume?: number;
+    /** Checks a keypad's code; without it, the code is compared to data-code */
+    onKeypadSubmit?: (code: string, keypad: HTMLElement) => boolean | void;
+}
+interface LcarsController {
+    play(kind?: LcarsSoundKind): void;
+    setSound(enabled: boolean): void;
+    destroy(): void;
+}
+/** Event a toggle dispatches after every change (detail.pressed). */
+declare const pressedChangeEvent = "lcar:pressedchange";
+/**
+ * Makes static markup interactive.
+ * The returned controller plays sounds and removes the listeners again.
+ */
+declare function initBehaviors(selectors: BehaviorSelectors, { root, sound, volume, onKeypadSubmit }?: InitBehaviorsOptions, soundOptions?: LcarsSoundOptions): LcarsController;
+
+declare const cx: (base: string, extra?: string) => string;
+
+/**
+ * Random numbers 0–1, but reproducible (mulberry32):
+ * same seed → same sequence, important for server rendering.
+ */
+declare function seededRandom(seed?: number): () => number;
+
+export { createLcarsSound, cx, initBehaviors, pressedChangeEvent, seededRandom };
+export type { BehaviorSelectors, InitBehaviorsOptions, LcarsController, LcarsSound, LcarsSoundKind, LcarsSoundOptions, LcarsSoundPatterns };

package/dist/index.js

@@ -0,0 +1,131 @@
+// src/sound.ts
+var defaultPatterns = {
+  beep: [[1320, 70]],
+  confirm: [[880, 70], [1320, 110]],
+  deny: [[440, 110], [330, 180]],
+  alert: [[620, 220], [880, 220], [620, 220], [880, 220]]
+};
+function createLcarsSound(volume = 0.12, { patterns = defaultPatterns, wave = "sine" } = {}) {
+  let ctx;
+  return {
+    play(kind = "beep") {
+      if (typeof AudioContext === "undefined") return;
+      ctx ?? (ctx = new AudioContext());
+      let t = ctx.currentTime;
+      for (const [freq, ms] of patterns[kind]) {
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        const end = t + ms / 1e3;
+        osc.type = wave;
+        osc.frequency.value = freq;
+        gain.gain.setValueAtTime(volume, t);
+        gain.gain.exponentialRampToValueAtTime(1e-4, end);
+        osc.connect(gain).connect(ctx.destination);
+        osc.start(t);
+        osc.stop(end);
+        t = end + 0.02;
+      }
+    }
+  };
+}
+
+// src/behaviors.ts
+var pressedChangeEvent = "lcar:pressedchange";
+function initBehaviors(selectors, { root = document, sound = false, volume, onKeypadSubmit } = {}, soundOptions) {
+  const player = createLcarsSound(volume, soundOptions);
+  let soundOn = sound;
+  const play = (kind) => soundOn && player.play(kind);
+  const onClick = (e) => {
+    const target = e.target;
+    const control = target.closest(selectors.control);
+    if (control && control.dataset.sound !== "none") play(control.dataset.sound || "beep");
+    const toggle = target.closest("[aria-pressed]");
+    if (toggle) {
+      const pressed = toggle.getAttribute("aria-pressed") !== "true";
+      toggle.setAttribute("aria-pressed", String(pressed));
+      toggle.dispatchEvent(new CustomEvent(pressedChangeEvent, { bubbles: true, detail: { pressed } }));
+    }
+    const tab = target.closest('[role="tab"]');
+    if (tab) selectTab(tab);
+    const key = target.closest(`${selectors.keypad} ${selectors.keypadKey}`);
+    if (key) pressKey(key.closest(selectors.keypad), key.textContent.trim());
+  };
+  const onKeyDown = (e) => {
+    const { key, target } = e;
+    const step = key === "ArrowRight" ? 1 : key === "ArrowLeft" ? -1 : 0;
+    const tab = target.closest('[role="tab"]');
+    if (!step || !tab) return;
+    const list = tabsOf(tab);
+    const next = list[(list.indexOf(tab) + step + list.length) % list.length];
+    selectTab(next);
+    play("beep");
+    next.focus();
+  };
+  const codes = /* @__PURE__ */ new WeakMap();
+  const pressKey = (pad, key) => {
+    const display = pad.querySelector(selectors.keypadDisplay);
+    const length = Number(pad.dataset.length) || 6;
+    let code = codes.get(pad) ?? "";
+    const show = (text, state) => {
+      if (!display) return;
+      display.textContent = text || "\u2013".repeat(length);
+      if (state) display.dataset.state = state;
+      else delete display.dataset.state;
+    };
+    if (key === "ENT") {
+      const accepted = onKeypadSubmit ? onKeypadSubmit(code, pad) : code === pad.dataset.code;
+      codes.set(pad, "");
+      if (accepted === void 0) return play("confirm");
+      play(accepted ? "confirm" : "deny");
+      return show(accepted ? "OK" : "Denied", accepted ? "ok" : "error");
+    }
+    if (key === "CLR") code = "";
+    else if (code.length < length) code += key;
+    codes.set(pad, code);
+    show(pad.dataset.mask === void 0 ? code : "\u2022".repeat(code.length));
+  };
+  root.addEventListener("click", onClick);
+  root.addEventListener("keydown", onKeyDown);
+  return {
+    play: (kind) => player.play(kind),
+    setSound: (enabled) => soundOn = enabled,
+    destroy() {
+      root.removeEventListener("click", onClick);
+      root.removeEventListener("keydown", onKeyDown);
+    }
+  };
+}
+function tabsOf(tab) {
+  return [...tab.closest('[role="tablist"]')?.querySelectorAll('[role="tab"]') ?? []];
+}
+function selectTab(tab) {
+  for (const t of tabsOf(tab)) {
+    const on = t === tab;
+    t.setAttribute("aria-selected", String(on));
+    t.tabIndex = on ? 0 : -1;
+    const panel = document.getElementById(t.getAttribute("aria-controls") ?? "");
+    if (panel) panel.hidden = !on;
+  }
+}
+
+// src/cx.ts
+var cx = (base, extra) => extra ? `${base} ${extra}` : base;
+
+// src/random.ts
+function seededRandom(seed = 47) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+export {
+  createLcarsSound,
+  cx,
+  initBehaviors,
+  pressedChangeEvent,
+  seededRandom
+};

package/dist/react/index.d.ts

@@ -0,0 +1,22 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type LcarsSoundKind = "beep" | "confirm" | "deny" | "alert";
+/** [frequency in Hz, duration in ms] for each tone of a pattern */
+type LcarsSoundPatterns = Record<LcarsSoundKind, [number, number][]>;
+
+interface SoundProviderProps {
+    enabled?: boolean;
+    volume?: number;
+    /** Custom sound patterns (e.g. a faction's) */
+    patterns?: LcarsSoundPatterns;
+    wave?: OscillatorType;
+    children?: ReactNode;
+}
+/** Enables interface sounds for all components below. */
+declare function SoundProvider({ enabled, volume, patterns, wave, children }: SoundProviderProps): react.JSX.Element;
+/** Returns play(kind); without a SoundProvider (or when disabled) nothing happens. */
+declare function useLcarsSound(): (kind?: LcarsSoundKind) => void | undefined;
+
+export { SoundProvider, useLcarsSound };
+export type { SoundProviderProps };

package/dist/react/index.js

@@ -0,0 +1,56 @@
+"use client";
+
+// src/react/Sound.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo
+} from "react";
+
+// src/sound.ts
+var defaultPatterns = {
+  beep: [[1320, 70]],
+  confirm: [[880, 70], [1320, 110]],
+  deny: [[440, 110], [330, 180]],
+  alert: [[620, 220], [880, 220], [620, 220], [880, 220]]
+};
+function createLcarsSound(volume = 0.12, { patterns = defaultPatterns, wave = "sine" } = {}) {
+  let ctx;
+  return {
+    play(kind = "beep") {
+      if (typeof AudioContext === "undefined") return;
+      ctx ?? (ctx = new AudioContext());
+      let t = ctx.currentTime;
+      for (const [freq, ms] of patterns[kind]) {
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        const end = t + ms / 1e3;
+        osc.type = wave;
+        osc.frequency.value = freq;
+        gain.gain.setValueAtTime(volume, t);
+        gain.gain.exponentialRampToValueAtTime(1e-4, end);
+        osc.connect(gain).connect(ctx.destination);
+        osc.start(t);
+        osc.stop(end);
+        t = end + 0.02;
+      }
+    }
+  };
+}
+
+// src/react/Sound.tsx
+import { jsx } from "react/jsx-runtime";
+var SoundContext = createContext(null);
+function SoundProvider({ enabled = true, volume, patterns, wave, children }) {
+  const sound = useMemo(() => createLcarsSound(volume, { patterns, wave }), [volume, patterns, wave]);
+  return /* @__PURE__ */ jsx(SoundContext.Provider, { value: enabled ? sound : null, children });
+}
+function useLcarsSound() {
+  const sound = useContext(SoundContext);
+  return useCallback((kind) => sound?.play(kind), [sound]);
+}
+export {
+  SoundProvider,
+  useLcarsSound
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@lcars-gui/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Shared foundation for all lcars-gui factions: sound engine, plain HTML/JS behavior, CSS build",
+  "keywords": [
+    "lcars",
+    "star-trek",
+    "ui",
+    "sound"
+  ],
+  "license": "MIT",
+  "author": "aarondnas",
+  "homepage": "https://aarondnas.github.io/lcars-gui/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aarondnas/lcars-gui.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/aarondnas/lcars-gui/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./build": "./build/css.js"
+  },
+  "files": [
+    "dist",
+    "build"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}