@mourtazag/blah 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 mourtazag
+
+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 USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# blah
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Open-source **browser** console logger with a namespace badge and per-argument colors using `console` `%c` CSS.
+
+> **Browser only** — relies on DevTools `%c` styling. Not for Node/terminal output.
+
+## Install
+
+```bash
+npm install @mourtazag/blah
+```
+
+## Quick start
+
+```ts
+import Blah from '@mourtazag/blah'
+
+const logger = new Blah({
+  namespace: {
+    name: 'App',
+    style: { color: 'white', bgColor: '#f97316' },
+  },
+  argStyles: [
+    { color: 'white', bgColor: '#2563eb' },
+    { color: 'black', bgColor: '#facc15' },
+  ],
+})
+
+logger.log('user clicked', 'button#submit')
+logger.warn('slow request', { ms: 420 })
+```
+
+Open DevTools → **Console** to see colored badges.
+
+## Examples
+
+### Console output
+
+Each segment gets its own colored badge (namespace + one badge per argument):
+
+![Console example showing styled badges for namespace and log arguments](./docs/images/console-example.png)
+
+### Playground
+
+Run `npm run dev` and open http://localhost:3000 to try the interactive demo:
+
+![Playground demo page with HTML, CSS, and JS sections](./docs/images/playground.png)
+
+## Logging controls
+
+Mute output globally or per level:
+
+```ts
+const logger = new Blah({
+  namespace: { name: 'App' },
+  logging: {
+    enabled: true,
+    log: true,
+    info: true,
+    warn: false,
+    error: true,
+  },
+})
+```
+
+**Debug mode** overrides `logging` and always prints:
+
+```ts
+const logger = new Blah({
+  namespace: { name: 'App' },
+  logging: { enabled: false },
+  debug: import.meta.env.DEV,
+})
+
+logger.setDebug(true)
+logger.setLogging({ warn: false })
+logger.isEnabled('warn') // false unless debug is on
+```
+
+## API
+
+### `new Blah(options)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `namespace` | `NamespaceConfig` | Badge label + optional `style` |
+| `argStyles` | `BadgeStyle[]` | CSS per log argument (by index) |
+| `logging` | `LoggingConfig` | Enable/disable levels |
+| `debug` | `boolean` | Force all levels on |
+
+### Methods
+
+- `log(...args)` / `info` / `warn` / `error`
+- `setLogging(config)` — merge logging flags
+- `setDebug(debug)` — toggle debug override
+- `isEnabled(level)` — check if a level would print
+
+### Types (exported)
+
+`BadgeStyle`, `NamespaceConfig`, `BlahOptions`, `LoggingConfig`, `LogLevel`
+
+## Local development
+
+```bash
+git clone <your-repo-url>
+cd blah
+npm install
+npm run dev          # playground at http://localhost:3000
+npm test
+npm run build:lib    # dist/ for npm
+npm pack --dry-run   # preview published tarball
+```
+
+Playground lives in `playground/`; the publishable package is `src/` → `dist/`.
+
+## License
+
+This project is **open source** under the [MIT License](LICENSE).
+
+You may use, copy, modify, and distribute it freely, including in commercial projects, as long as the copyright and license notice are included.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/** Colors for one console badge */
+interface BadgeStyle {
+    color?: string;
+    bgColor?: string;
+}
+interface NamespaceConfig {
+    name?: string;
+    style?: BadgeStyle;
+}
+type LogLevel = 'log' | 'info' | 'warn' | 'error';
+interface LoggingConfig {
+    /** Master switch — when false, nothing is printed */
+    enabled?: boolean;
+    log?: boolean;
+    info?: boolean;
+    warn?: boolean;
+    error?: boolean;
+}
+interface BlahOptions {
+    namespace: NamespaceConfig;
+    /** One style per log argument, by index (0 = first value after the namespace badge) */
+    argStyles?: BadgeStyle[];
+    logging?: LoggingConfig;
+    /**
+     * When true, prints every level regardless of `logging`.
+     * Useful in dev to force output while keeping production logging muted.
+     */
+    debug?: boolean;
+}
+
+declare class Blah {
+    private readonly namespace;
+    private readonly namespaceStyle;
+    /** CSS strings ready for console — built once in the constructor */
+    private readonly resolvedArgStyles;
+    private logging;
+    private debug;
+    constructor(options: BlahOptions);
+    /** Force all levels on/off, overriding `logging` restrictions */
+    setDebug(debug: boolean): void;
+    /** Update logging flags (merged with current settings) */
+    setLogging(config: LoggingConfig): void;
+    isEnabled(level: LogLevel): boolean;
+    private print;
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+
+export { type BadgeStyle, Blah, type BlahOptions, type LogLevel, type LoggingConfig, type NamespaceConfig, Blah as default };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/blah-utils.ts
+var BASE_BADGE = "padding: 2px 4px; margin: 2px; border-radius: 4px; font-weight: bold;";
+var DEFAULT_NAMESPACE_STYLE = {
+  color: "white",
+  bgColor: "black"
+};
+var DEFAULT_ARG_STYLE = {
+  color: "inherit",
+  bgColor: "transparent"
+};
+function resolveLogging(config = {}) {
+  const enabled = config.enabled ?? true;
+  if (!enabled) {
+    return { enabled: false, log: false, info: false, warn: false, error: false };
+  }
+  return {
+    enabled: true,
+    log: config.log ?? true,
+    info: config.info ?? true,
+    warn: config.warn ?? true,
+    error: config.error ?? true
+  };
+}
+function toCss(style, fallback = {}) {
+  const color = style.color ?? fallback.color ?? DEFAULT_ARG_STYLE.color;
+  const bgColor = style.bgColor ?? fallback.bgColor ?? DEFAULT_ARG_STYLE.bgColor;
+  return `${BASE_BADGE} color: ${color}; background-color: ${bgColor};`;
+}
+function formatArg(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "object" && value !== null) {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function buildConsolePayload(namespace, namespaceStyle, resolvedArgStyles, args) {
+  let format = `%c${namespace}`;
+  const styles = [namespaceStyle];
+  for (const [index, arg] of args.entries()) {
+    format += ` %c${formatArg(arg)}`;
+    styles.push(resolvedArgStyles[index] ?? toCss({}));
+  }
+  return [format, ...styles];
+}
+
+// src/Blah.ts
+var Blah = class {
+  namespace;
+  namespaceStyle;
+  /** CSS strings ready for console — built once in the constructor */
+  resolvedArgStyles;
+  logging;
+  debug;
+  constructor(options) {
+    this.namespace = options.namespace.name ?? "Blah";
+    this.namespaceStyle = toCss(
+      options.namespace.style ?? {},
+      DEFAULT_NAMESPACE_STYLE
+    );
+    this.resolvedArgStyles = (options.argStyles ?? []).map((style) => toCss(style));
+    this.logging = resolveLogging(options.logging);
+    this.debug = options.debug ?? false;
+  }
+  /** Force all levels on/off, overriding `logging` restrictions */
+  setDebug(debug) {
+    this.debug = debug;
+  }
+  /** Update logging flags (merged with current settings) */
+  setLogging(config) {
+    this.logging = resolveLogging({
+      enabled: config.enabled ?? this.logging.enabled,
+      log: config.log ?? this.logging.log,
+      info: config.info ?? this.logging.info,
+      warn: config.warn ?? this.logging.warn,
+      error: config.error ?? this.logging.error
+    });
+  }
+  isEnabled(level) {
+    return this.debug || this.logging.enabled && this.logging[level];
+  }
+  print(method, ...args) {
+    if (!this.isEnabled(method)) return;
+    console[method](
+      ...buildConsolePayload(
+        this.namespace,
+        this.namespaceStyle,
+        this.resolvedArgStyles,
+        args
+      )
+    );
+  }
+  log(...args) {
+    this.print("log", ...args);
+  }
+  info(...args) {
+    this.print("info", ...args);
+  }
+  warn(...args) {
+    this.print("warn", ...args);
+  }
+  error(...args) {
+    this.print("error", ...args);
+  }
+};
+var Blah_default = Blah;
+export {
+  Blah_default as Blah,
+  Blah_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/blah-utils.ts","../src/Blah.ts"],"sourcesContent":["import type { BadgeStyle, LoggingConfig } from './blah-types'\n\nexport const BASE_BADGE =\n  'padding: 2px 4px; margin: 2px; border-radius: 4px; font-weight: bold;'\n\nexport const DEFAULT_NAMESPACE_STYLE: Required<BadgeStyle> = {\n  color: 'white',\n  bgColor: 'black',\n}\n\nexport const DEFAULT_ARG_STYLE: Required<BadgeStyle> = {\n  color: 'inherit',\n  bgColor: 'transparent',\n}\n\nexport const DEFAULT_LOGGING: Required<LoggingConfig> = {\n  enabled: true,\n  log: true,\n  info: true,\n  warn: true,\n  error: true,\n}\n\n/** Resolve logging flags; global `enabled: false` turns off every level */\nexport function resolveLogging(config: LoggingConfig = {}): Required<LoggingConfig> {\n  const enabled = config.enabled ?? true\n  if (!enabled) {\n    return { enabled: false, log: false, info: false, warn: false, error: false }\n  }\n  return {\n    enabled: true,\n    log: config.log ?? true,\n    info: config.info ?? true,\n    warn: config.warn ?? true,\n    error: config.error ?? true,\n  }\n}\n\n/** Turn { color, bgColor } into a CSS string for console %c */\nexport function toCss(style: BadgeStyle, fallback: BadgeStyle = {}): string {\n  const color = style.color ?? fallback.color ?? DEFAULT_ARG_STYLE.color\n  const bgColor = style.bgColor ?? fallback.bgColor ?? DEFAULT_ARG_STYLE.bgColor\n  return `${BASE_BADGE} color: ${color}; background-color: ${bgColor};`\n}\n\n/** Convert any log value into text for a %c badge */\nexport function formatArg(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'object' && value !== null) {\n    try {\n      return JSON.stringify(value)\n    } catch {\n      return String(value)\n    }\n  }\n  return String(value)\n}\n\n/** Build the format string + CSS values that console.log expects */\nexport function buildConsolePayload(\n  namespace: string,\n  namespaceStyle: string,\n  resolvedArgStyles: string[],\n  args: unknown[],\n): [string, ...string[]] {\n  let format = `%c${namespace}`\n  const styles: string[] = [namespaceStyle]\n\n  for (const [index, arg] of args.entries()) {\n    format += ` %c${formatArg(arg)}`\n    styles.push(resolvedArgStyles[index] ?? toCss({}))\n  }\n\n  return [format, ...styles]\n}\n","import type { BlahOptions, LogLevel, LoggingConfig } from './blah-types'\nimport {\n  buildConsolePayload,\n  DEFAULT_NAMESPACE_STYLE,\n  resolveLogging,\n  toCss,\n} from './blah-utils'\n\nexport type {\n  BadgeStyle,\n  BlahOptions,\n  LogLevel,\n  LoggingConfig,\n  NamespaceConfig,\n} from './blah-types'\n\nclass Blah {\n  private readonly namespace: string\n  private readonly namespaceStyle: string\n  /** CSS strings ready for console — built once in the constructor */\n  private readonly resolvedArgStyles: string[]\n  private logging: Required<LoggingConfig>\n  private debug: boolean\n\n  constructor(options: BlahOptions) {\n    this.namespace = options.namespace.name ?? 'Blah'\n    this.namespaceStyle = toCss(\n      options.namespace.style ?? {},\n      DEFAULT_NAMESPACE_STYLE,\n    )\n    this.resolvedArgStyles = (options.argStyles ?? []).map(style => toCss(style))\n    this.logging = resolveLogging(options.logging)\n    this.debug = options.debug ?? false\n  }\n\n  /** Force all levels on/off, overriding `logging` restrictions */\n  setDebug(debug: boolean): void {\n    this.debug = debug\n  }\n\n  /** Update logging flags (merged with current settings) */\n  setLogging(config: LoggingConfig): void {\n    this.logging = resolveLogging({\n      enabled: config.enabled ?? this.logging.enabled,\n      log: config.log ?? this.logging.log,\n      info: config.info ?? this.logging.info,\n      warn: config.warn ?? this.logging.warn,\n      error: config.error ?? this.logging.error,\n    })\n  }\n\n  isEnabled(level: LogLevel): boolean {\n    return this.debug || (this.logging.enabled && this.logging[level])\n  }\n\n  private print(method: LogLevel, ...args: unknown[]): void {\n    if (!this.isEnabled(method)) return\n\n    console[method](\n      ...buildConsolePayload(\n        this.namespace,\n        this.namespaceStyle,\n        this.resolvedArgStyles,\n        args,\n      ),\n    )\n  }\n\n  log(...args: unknown[]): void {\n    this.print('log', ...args)\n  }\n\n  info(...args: unknown[]): void {\n    this.print('info', ...args)\n  }\n\n  warn(...args: unknown[]): void {\n    this.print('warn', ...args)\n  }\n\n  error(...args: unknown[]): void {\n    this.print('error', ...args)\n  }\n}\n\nexport default Blah\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mourtazag/blah",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "Styled browser console logger with namespace badges and per-argument colors",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run build:lib && npm run build:playground",
+    "build:lib": "tsup",
+    "build:playground": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "screenshots": "node scripts/capture-screenshots.mjs",
+    "prepublishOnly": "npm test && npm run build:lib"
+  },
+  "keywords": [
+    "console",
+    "logger",
+    "browser",
+    "debug",
+    "typescript"
+  ],
+  "author": "mourtazag",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mourtazag/blah.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mourtazag/blah/issues"
+  },
+  "homepage": "https://github.com/mourtazag/blah#readme",
+  "devDependencies": {
+    "playwright": "^1.60.0",
+    "prettier": "^3.8.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^6.3.5",
+    "vitest": "^4.1.7"
+  }
+}