@favish/staffbase-utils 0.1.0 → 0.2.0

package/README.md

@@ -3,19 +3,77 @@
 Shared internal/host utilities for Staffbase widgets. Tree-shakeable subpath
 modules; import only what you use.
 
+## Install
+
+```bash
+pnpm add @favish/staffbase-utils
+```
+
+Widgets that enforce a `minimumReleaseAge` supply-chain cooldown should exempt the
+`@favish/*` scope so freshly published versions install immediately. In the
+widget's `pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAge: 1440
+minimumReleaseAgeExclude:
+  - '@favish/*'
+```
+
 ## Modules
 
-- `@favish/staffbase-utils/log` — `logError`, `logWarn`, `logDebug`, `setLoggingEnabled`
+| Subpath | Exports |
+| --- | --- |
+| `@favish/staffbase-utils/log` | `logError`, `logWarn`, `logDebug`, `setLoggingEnabled` |
+
+More modules (`/env`, `/device`, `/html`, `/links`, `/widgets`) are added per the
+delivery roadmap; each is its own subpath so consumers only bundle what they import.
 
 ## Logging
 
-The library never reads env flags directly (webview-safe). Enable console output
-once at widget startup with your own flag:
+The library never reads env flags directly (webview-safe: a bundled `process.env`
+reference would crash inside Staffbase mobile webviews). Enable console output once
+at widget startup with your own flag:
 
 ```ts
 import { setLoggingEnabled } from '@favish/staffbase-utils/log'
 
 setLoggingEnabled(import.meta.env.VITE_SHOW_CONSOLE_ERRORS === 'true')
+// or, for REACT_APP_-style widgets:
+// setLoggingEnabled(process.env.REACT_APP_SHOW_CONSOLE_ERRORS === 'true')
+```
+
+Disabled by default, so production stays silent. `logError`/`logWarn`/`logDebug`
+forward to the matching `console` method only while enabled.
+
+## Releasing
+
+Publishing runs through GitHub Actions with npm **Trusted Publishing (OIDC)** — no
+tokens, no OTP — same as `@favish/staffbase-drawer` and `@favish/staffbase-cli`.
+
+Trigger the `Release` workflow (`.github/workflows/release.yml`) manually and pick a
+bump type:
+
+```bash
+gh workflow run release.yml -f release_type=patch   # or minor / major / none
+```
+
+(or run it from the GitHub Actions tab). The workflow runs the quality gate
+(type-check, lint, test, build), bumps + tags the version, publishes to npm with
+provenance, and pushes the version commit + tag back to `main`. Use
+`release_type=none` to publish the current `package.json` version as-is.
+
+CI (`.github/workflows/ci.yml`) runs the same quality gate on every push and PR to
+`main`.
+
+## Development
+
+```bash
+pnpm install      # installs deps and runs the full verify+build via `prepare`
+pnpm test         # jest
+pnpm run type-check
+pnpm run lint
+pnpm run build    # vite library build -> dist/
 ```
 
-Disabled by default, so production stays silent.
+Conventions: one exported symbol per file; types under `src/types/`; ESM + CJS
+outputs per module (`*.es.mjs` / `*.cjs.js`) with generated `.d.ts`.

package/dist/device.cjs.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=()=>{if(typeof navigator>`u`)return!1;let e=navigator.userAgent.toLowerCase(),t=/mobile|android|ios|iphone|ipad|ipod|windows phone/i.test(e),n=/wv|webview/i.test(e);return t||n},t=()=>typeof window>`u`?!1:window.innerWidth<=768,n=()=>e()||t();exports.isMobile=n,exports.isMobileOrWebview=e,exports.isMobileViewport=t;
+//# sourceMappingURL=device.cjs.js.map

package/dist/device.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.cjs.js","names":[],"sources":["../src/device/isMobileOrWebview.ts","../src/device/isMobileViewport.ts","../src/device/isMobile.ts"],"sourcesContent":["/**\n * Detects if the current environment is a mobile device or running inside a\n * webview, using userAgent heuristics common on iOS/Android and webviews.\n * Guards against non-browser environments (SSR/tests without navigator).\n * @returns {boolean} True if likely mobile or webview.\n */\nexport const isMobileOrWebview = (): boolean => {\n  if (typeof navigator === 'undefined') return false\n\n  const userAgent = navigator.userAgent.toLowerCase()\n  const isMobilePlatform =\n    /mobile|android|ios|iphone|ipad|ipod|windows phone/i.test(userAgent)\n  const isWebview = /wv|webview/i.test(userAgent)\n\n  return isMobilePlatform || isWebview\n}\n","/**\n * Checks if the viewport width is mobile-sized (<= 768px).\n * Guards against non-browser environments (SSR/tests without window).\n * @returns {boolean} True if the viewport width is 768px or less.\n */\nexport const isMobileViewport = (): boolean => {\n  if (typeof window === 'undefined') return false\n  return window.innerWidth <= 768\n}\n","import { isMobileOrWebview } from './isMobileOrWebview'\nimport { isMobileViewport } from './isMobileViewport'\n\n/**\n * Checks if the device is mobile either by user agent/webview or viewport size.\n * @returns {boolean} True if either a mobile/webview UA or a mobile viewport.\n */\nexport const isMobile = (): boolean =>\n  isMobileOrWebview() || isMobileViewport()\n"],"mappings":"mEAMA,IAAa,MAAmC,CAC9C,GAAI,OAAO,UAAc,IAAa,MAAO,GAE7C,IAAM,EAAY,UAAU,UAAU,YAAY,EAC5C,EACJ,qDAAqD,KAAK,CAAS,EAC/D,EAAY,cAAc,KAAK,CAAS,EAE9C,OAAO,GAAoB,CAC7B,ECVa,MACP,OAAO,OAAW,IAAoB,GACnC,OAAO,YAAc,ICAjB,MACX,EAAkB,GAAK,EAAiB"}

package/dist/device.es.mjs

@@ -0,0 +1,10 @@
+//#region src/device/isMobileOrWebview.ts
+var e = () => {
+	if (typeof navigator > "u") return !1;
+	let e = navigator.userAgent.toLowerCase(), t = /mobile|android|ios|iphone|ipad|ipod|windows phone/i.test(e), n = /wv|webview/i.test(e);
+	return t || n;
+}, t = () => typeof window > "u" ? !1 : window.innerWidth <= 768, n = () => e() || t();
+//#endregion
+export { n as isMobile, e as isMobileOrWebview, t as isMobileViewport };
+
+//# sourceMappingURL=device.es.mjs.map

package/dist/device.es.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.es.mjs","names":[],"sources":["../src/device/isMobileOrWebview.ts","../src/device/isMobileViewport.ts","../src/device/isMobile.ts"],"sourcesContent":["/**\n * Detects if the current environment is a mobile device or running inside a\n * webview, using userAgent heuristics common on iOS/Android and webviews.\n * Guards against non-browser environments (SSR/tests without navigator).\n * @returns {boolean} True if likely mobile or webview.\n */\nexport const isMobileOrWebview = (): boolean => {\n  if (typeof navigator === 'undefined') return false\n\n  const userAgent = navigator.userAgent.toLowerCase()\n  const isMobilePlatform =\n    /mobile|android|ios|iphone|ipad|ipod|windows phone/i.test(userAgent)\n  const isWebview = /wv|webview/i.test(userAgent)\n\n  return isMobilePlatform || isWebview\n}\n","/**\n * Checks if the viewport width is mobile-sized (<= 768px).\n * Guards against non-browser environments (SSR/tests without window).\n * @returns {boolean} True if the viewport width is 768px or less.\n */\nexport const isMobileViewport = (): boolean => {\n  if (typeof window === 'undefined') return false\n  return window.innerWidth <= 768\n}\n","import { isMobileOrWebview } from './isMobileOrWebview'\nimport { isMobileViewport } from './isMobileViewport'\n\n/**\n * Checks if the device is mobile either by user agent/webview or viewport size.\n * @returns {boolean} True if either a mobile/webview UA or a mobile viewport.\n */\nexport const isMobile = (): boolean =>\n  isMobileOrWebview() || isMobileViewport()\n"],"mappings":";AAMA,IAAa,UAAmC;CAC9C,IAAI,OAAO,YAAc,KAAa,OAAO;CAE7C,IAAM,IAAY,UAAU,UAAU,YAAY,GAC5C,IACJ,qDAAqD,KAAK,CAAS,GAC/D,IAAY,cAAc,KAAK,CAAS;CAE9C,OAAO,KAAoB;AAC7B,GCVa,UACP,OAAO,SAAW,MAAoB,KACnC,OAAO,cAAc,KCAjB,UACX,EAAkB,KAAK,EAAiB"}

package/dist/src/device/index.d.ts

@@ -0,0 +1,4 @@
+export { isMobile } from './isMobile';
+export { isMobileOrWebview } from './isMobileOrWebview';
+export { isMobileViewport } from './isMobileViewport';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/device/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/device/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/src/device/isMobile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if the device is mobile either by user agent/webview or viewport size.
+ * @returns {boolean} True if either a mobile/webview UA or a mobile viewport.
+ */
+export declare const isMobile: () => boolean;
+//# sourceMappingURL=isMobile.d.ts.map

package/dist/src/device/isMobile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isMobile.d.ts","sourceRoot":"","sources":["../../../src/device/isMobile.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAO,OACe,CAAA"}

package/dist/src/device/isMobileOrWebview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Detects if the current environment is a mobile device or running inside a
+ * webview, using userAgent heuristics common on iOS/Android and webviews.
+ * Guards against non-browser environments (SSR/tests without navigator).
+ * @returns {boolean} True if likely mobile or webview.
+ */
+export declare const isMobileOrWebview: () => boolean;
+//# sourceMappingURL=isMobileOrWebview.d.ts.map

package/dist/src/device/isMobileOrWebview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isMobileOrWebview.d.ts","sourceRoot":"","sources":["../../../src/device/isMobileOrWebview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAO,OASpC,CAAA"}

package/dist/src/device/isMobileViewport.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if the viewport width is mobile-sized (<= 768px).
+ * Guards against non-browser environments (SSR/tests without window).
+ * @returns {boolean} True if the viewport width is 768px or less.
+ */
+export declare const isMobileViewport: () => boolean;
+//# sourceMappingURL=isMobileViewport.d.ts.map

package/dist/src/device/isMobileViewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isMobileViewport.d.ts","sourceRoot":"","sources":["../../../src/device/isMobileViewport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAGnC,CAAA"}

package/package.json

@@ -1,38 +1,27 @@
 {
   "name": "@favish/staffbase-utils",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared internal/host utilities for Staffbase widgets",
   "author": "Favish <dev@favish.com>",
-  "packageManager": "pnpm@11.5.0",
   "license": "UNLICENSED",
-  "type": "module",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
     "./log": {
       "types": "./dist/src/log/index.d.ts",
       "import": "./dist/log.es.mjs",
       "require": "./dist/log.cjs.js"
+    },
+    "./device": {
+      "types": "./dist/src/device/index.d.ts",
+      "import": "./dist/device.es.mjs",
+      "require": "./dist/device.cjs.js"
     }
   },
-  "scripts": {
-    "build": "vite build",
-    "check:all": "pnpm run format && pnpm run lint:fix && pnpm run type-check && pnpm run test",
-    "format": "prettier --write \"src/**/*\" --list-different",
-    "lint": "eslint ./src",
-    "lint:fix": "eslint ./src --fix",
-    "prepare": "pnpm run format && pnpm run type-check && pnpm run lint:fix && pnpm run build",
-    "prepublishOnly": "pnpm run test",
-    "publish:major": "pnpm run prepare && pnpm version major && pnpm publish",
-    "publish:minor": "pnpm run prepare && pnpm version minor && pnpm publish",
-    "publish:patch": "pnpm run prepare && pnpm version patch && pnpm publish",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "type-check": "tsc --pretty --noEmit",
-    "type-check:watch": "tsc --pretty --noEmit --watch"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/favish/staffbase-utils"
+    "url": "git+https://github.com/favish/staffbase-utils.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -43,8 +32,12 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",
@@ -69,5 +62,19 @@
     "typescript-eslint": "^8.60.0",
     "vite": "^8.0.14",
     "vite-plugin-dts": "^5.0.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "check:all": "pnpm run format && pnpm run lint:fix && pnpm run type-check && pnpm run test",
+    "format": "prettier --write \"src/**/*\" --list-different",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "publish:major": "pnpm run prepare && pnpm version major && pnpm publish",
+    "publish:minor": "pnpm run prepare && pnpm version minor && pnpm publish",
+    "publish:patch": "pnpm run prepare && pnpm version patch && pnpm publish",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "type-check": "tsc --pretty --noEmit",
+    "type-check:watch": "tsc --pretty --noEmit --watch"
   }
-}
+}