@dnax/ui 0.0.63 → 0.0.65

package/lib/wakeLock.test.ts

@@ -0,0 +1,219 @@
+// $q.wakeLock — Screen Wake Lock : logique pure + fabrique testable hors navigateur.
+import { describe, expect, it } from "bun:test"
+import {
+  createWakeLock,
+  isDocumentVisible,
+  isWakeLockCapable,
+  shouldReacquire,
+} from "./wakeLock"
+
+class FakeSentinel {
+  released = false
+  releaseCalls = 0
+  private listeners = new Set<() => void>()
+
+  async release() {
+    this.releaseCalls++
+    this.released = true
+    for (const cb of [...this.listeners]) cb()
+  }
+
+  addEventListener(_type: "release", cb: () => void) {
+    this.listeners.add(cb)
+  }
+
+  removeEventListener(_type: "release", cb: () => void) {
+    this.listeners.delete(cb)
+  }
+
+  /** Simule le relâchement décidé par le navigateur (page masquée, veille…). */
+  autoRelease() {
+    this.released = true
+    for (const cb of [...this.listeners]) cb()
+  }
+}
+
+function fakeApi(options: { fail?: Error } = {}) {
+  const sentinels: FakeSentinel[] = []
+  return {
+    calls: 0,
+    sentinels,
+    async request(_type: "screen") {
+      this.calls++
+      if (options.fail) throw options.fail
+      const s = new FakeSentinel()
+      sentinels.push(s)
+      return s
+    },
+  }
+}
+
+function fakeVisibility(state = "visible") {
+  const listeners = new Set<() => void>()
+  return {
+    visibilityState: state as string,
+    addEventListener(_type: "visibilitychange", cb: () => void) {
+      listeners.add(cb)
+    },
+    removeEventListener(_type: "visibilitychange", cb: () => void) {
+      listeners.delete(cb)
+    },
+    set(next: string) {
+      this.visibilityState = next
+      for (const cb of [...listeners]) cb()
+    },
+    count() {
+      return listeners.size
+    },
+  }
+}
+
+function client(options: Partial<Parameters<typeof createWakeLock>[0]> = {}) {
+  return createWakeLock({
+    server: false,
+    deferCapability: false,
+    api: fakeApi(),
+    visibility: fakeVisibility(),
+    ...options,
+  })
+}
+
+describe("isWakeLockCapable", () => {
+  it("exige une API avec request()", () => {
+    expect(isWakeLockCapable(null)).toBe(false)
+    expect(isWakeLockCapable(undefined)).toBe(false)
+    expect(isWakeLockCapable({} as never)).toBe(false)
+    expect(isWakeLockCapable({ request: async () => new FakeSentinel() })).toBe(true)
+  })
+})
+
+describe("isDocumentVisible", () => {
+  it("visible sauf `visibilityState: 'hidden'` (et sans document injecté)", () => {
+    expect(isDocumentVisible(null)).toBe(true)
+    expect(isDocumentVisible({ addEventListener() {} })).toBe(true)
+    expect(
+      isDocumentVisible({ visibilityState: "visible", addEventListener() {} }),
+    ).toBe(true)
+    expect(
+      isDocumentVisible({ visibilityState: "hidden", addEventListener() {} }),
+    ).toBe(false)
+  })
+})
+
+describe("shouldReacquire", () => {
+  it("uniquement si demandé, visible et rien de tenu", () => {
+    expect(shouldReacquire(true, true, false)).toBe(true)
+    expect(shouldReacquire(false, true, false)).toBe(false)
+    expect(shouldReacquire(true, false, false)).toBe(false)
+    expect(shouldReacquire(true, true, true)).toBe(false)
+  })
+})
+
+describe("createWakeLock", () => {
+  it("au serveur : méthodes sans effet, rien de capable ni d'actif", async () => {
+    const lock = createWakeLock({ server: true })
+    expect(lock.isCapable).toBe(false)
+    expect(lock.isActive).toBe(false)
+    await expect(lock.request()).resolves.toBeUndefined()
+    await expect(lock.release()).resolves.toBeUndefined()
+  })
+
+  it("sans API : `Not capable`", async () => {
+    const lock = client({ api: null })
+    expect(lock.isCapable).toBe(false)
+    await expect(lock.request()).rejects.toThrow("Not capable")
+    expect(lock.isActive).toBe(false)
+  })
+
+  it("request() acquiert le verrou, une seule fois (idempotent)", async () => {
+    const api = fakeApi()
+    const lock = client({ api })
+
+    await lock.request()
+    expect(lock.isActive).toBe(true)
+    expect(api.calls).toBe(1)
+
+    await lock.request()
+    expect(api.calls).toBe(1)
+    expect(lock.isActive).toBe(true)
+  })
+
+  it("release() rend la main au système", async () => {
+    const api = fakeApi()
+    const lock = client({ api })
+
+    await lock.request()
+    await lock.release()
+
+    expect(lock.isActive).toBe(false)
+    expect(api.sentinels[0]!.releaseCalls).toBe(1)
+
+    // Une nouvelle demande fonctionne.
+    await lock.request()
+    expect(api.calls).toBe(2)
+    expect(lock.isActive).toBe(true)
+  })
+
+  it("le navigateur relâche → isActive retombe, et le verrou est redemandé au retour", async () => {
+    const api = fakeApi()
+    const visibility = fakeVisibility("visible")
+    const lock = client({ api, visibility })
+
+    await lock.request()
+    expect(lock.isActive).toBe(true)
+
+    // Onglet masqué : le navigateur relâche de lui-même.
+    visibility.set("hidden")
+    api.sentinels[0]!.autoRelease()
+    expect(lock.isActive).toBe(false)
+    expect(api.calls).toBe(1)
+
+    // Retour de visibilité : la demande mémorisée est rejouée.
+    visibility.set("visible")
+    await Promise.resolve()
+    expect(api.calls).toBe(2)
+    expect(lock.isActive).toBe(true)
+  })
+
+  it("après release(), plus aucune redemande au changement de visibilité", async () => {
+    const api = fakeApi()
+    const visibility = fakeVisibility("visible")
+    const lock = client({ api, visibility })
+
+    await lock.request()
+    await lock.release()
+
+    visibility.set("hidden")
+    visibility.set("visible")
+    await Promise.resolve()
+
+    expect(api.calls).toBe(1)
+    expect(lock.isActive).toBe(false)
+  })
+
+  it("le refus du navigateur est propagé (échec doux côté appelant)", async () => {
+    const api = fakeApi({ fail: new Error("denied") })
+    const lock = client({ api })
+
+    await expect(lock.request()).rejects.toThrow("denied")
+    expect(lock.isActive).toBe(false)
+  })
+
+  it("destroy() détache l'écouteur de visibilité", async () => {
+    const visibility = fakeVisibility()
+    const lock = client({ visibility })
+
+    expect(visibility.count()).toBe(1)
+    lock.destroy()
+    expect(visibility.count()).toBe(0)
+  })
+
+  it("isCapable n'est révélé qu'après hydratation (report d'un tick)", async () => {
+    const api = fakeApi()
+    const lock = createWakeLock({ server: false, api, visibility: null })
+
+    expect(lock.isCapable).toBe(false)
+    await new Promise((resolve) => setTimeout(resolve, 1))
+    expect(lock.isCapable).toBe(true)
+  })
+})

package/lib/wakeLock.ts

@@ -0,0 +1,202 @@
+// $q.wakeLock — Screen Wake Lock façon Quasar (`AppWakeLockPlugin`).
+// https://quasar.dev/quasar-plugins/app-wake-lock
+//
+// - `request()` garde l'écran allumé ; `release()` rend la main au délai système.
+// - `isActive` ne vaut `true` que **tant que le verrou est réellement tenu** : le
+//   navigateur le relâche de lui-même quand la page est masquée (onglet, veille…).
+//   La demande est alors **mémorisée** et rejouée au retour de visibilité, jusqu'à
+//   `release()`.
+// - `isCapable` vaut `false` au serveur **et au premier rendu client**, puis prend sa
+//   valeur réelle après hydratation (sinon le `v-if` d'un bouton « garder l'écran
+//   allumé » divergerait du HTML SSR).
+// - Sans API (navigateur non supporté), les méthodes rejettent `Not capable` ; au
+//   serveur elles se résolvent sans effet.
+//
+// Logique pure (`isWakeLockCapable`, `isDocumentVisible`, `shouldReacquire`) et fabrique
+// `createWakeLock` à dépendances injectables : testable sans DOM.
+import { reactive, ref } from "vue"
+
+/** Sentinel minimal du Screen Wake Lock API (injectable pour les tests). */
+export interface WakeLockSentinelLike {
+  /** Passe à `true` quand le navigateur relâche le verrou de lui-même */
+  released?: boolean
+  release: () => Promise<void>
+  addEventListener?: (type: "release", listener: () => void) => void
+  removeEventListener?: (type: "release", listener: () => void) => void
+}
+
+/** Sous-ensemble de `navigator.wakeLock`. */
+export interface WakeLockApiLike {
+  request: (type: "screen") => Promise<WakeLockSentinelLike>
+}
+
+/** Sous-ensemble de `document` utilisé pour suivre la visibilité. */
+export interface WakeLockVisibilityLike {
+  visibilityState?: string
+  addEventListener: (type: "visibilitychange", listener: () => void) => void
+  removeEventListener?: (type: "visibilitychange", listener: () => void) => void
+}
+
+export interface QWakeLock {
+  /** Un verrou est réellement tenu (réactif, lecture sans `.value`) */
+  readonly isActive: boolean
+  /** Screen Wake Lock disponible — `false` au serveur et avant hydratation */
+  readonly isCapable: boolean
+  /** Demande le verrou (idempotent). Rejette si non supporté (`Not capable`). */
+  request: () => Promise<void>
+  /** Relâche le verrou et cesse les redemandes automatiques */
+  release: () => Promise<void>
+  /** Détache l'écouteur de visibilité (instance de test / usage hors singleton) */
+  destroy: () => void
+}
+
+export interface WakeLockOptions {
+  /** API Screen Wake Lock (défaut : `navigator.wakeLock` ; `null` si absente) */
+  api?: WakeLockApiLike | null
+  /** Document pour la visibilité (défaut : `document` ; `null` au serveur) */
+  visibility?: WakeLockVisibilityLike | null
+  /** Force le mode serveur : aucune API lue, méthodes sans effet */
+  server?: boolean
+  /**
+   * Diffère `isCapable` après l'hydratation (défaut : `true` côté client) — évite un
+   * décalage entre le HTML SSR (`isCapable = false`) et le premier rendu client.
+   */
+  deferCapability?: boolean
+}
+
+/** `true` seulement si l'API Screen Wake Lock est exposée par le navigateur. */
+export function isWakeLockCapable(api?: WakeLockApiLike | null): boolean {
+  return !!api && typeof api.request === "function"
+}
+
+/** Une page est considérée visible sauf si le document dit explicitement `hidden`. */
+export function isDocumentVisible(visibility?: WakeLockVisibilityLike | null): boolean {
+  return visibility?.visibilityState !== "hidden"
+}
+
+/** Faut-il redemander le verrou ? (demandé, page visible, et rien de tenu) */
+export function shouldReacquire(wanted: boolean, visible: boolean, held: boolean): boolean {
+  return wanted && visible && !held
+}
+
+function notCapableError(): Error {
+  const message = "Not capable"
+  return typeof DOMException === "function"
+    ? new DOMException(message, "NotSupportedError")
+    : new Error(message)
+}
+
+/**
+ * Crée le gestionnaire de verrou. Sans `visibility`, aucune écoute n'est posée ;
+ * en mode serveur, `request()` / `release()` se résolvent sans effet.
+ */
+export function createWakeLock(options: WakeLockOptions = {}): QWakeLock {
+  const server = options.server ?? typeof window === "undefined"
+  const api = "api" in options
+    ? (options.api ?? null)
+    : typeof navigator !== "undefined"
+      ? ((navigator as Navigator & { wakeLock?: WakeLockApiLike }).wakeLock ?? null)
+      : null
+  const visibility = "visibility" in options
+    ? (options.visibility ?? null)
+    : typeof document !== "undefined"
+      ? document
+      : null
+
+  const active = ref(false)
+  const capable = ref(false)
+
+  // `isCapable` n'est révélé qu'après le rendu SSR/hydratation (cf. en-tête).
+  if (!server) {
+    if (options.deferCapability === false) {
+      capable.value = isWakeLockCapable(api)
+    }
+    else {
+      setTimeout(() => {
+        capable.value = isWakeLockCapable(api)
+      }, 0)
+    }
+  }
+
+  /** L'utilisateur veut garder l'écran allumé (survit aux relâchements du navigateur). */
+  let wanted = false
+  let sentinel: WakeLockSentinelLike | null = null
+  let pending: Promise<void> | null = null
+
+  const bindRelease = (s: WakeLockSentinelLike) => {
+    s.addEventListener?.("release", () => {
+      if (sentinel !== s) return
+      sentinel = null
+      active.value = false
+    })
+  }
+
+  const request = async (): Promise<void> => {
+    if (server) return
+    if (!isWakeLockCapable(api)) throw notCapableError()
+
+    wanted = true
+    if (sentinel && sentinel.released !== true) {
+      active.value = true
+      return
+    }
+    if (pending) return pending
+
+    pending = (async () => {
+      const s = await api!.request("screen")
+      if (!wanted) {
+        // `release()` a été appelé pendant la demande : ne pas reprendre le verrou.
+        await s.release().catch(() => {})
+        return
+      }
+      sentinel = s
+      active.value = true
+      bindRelease(s)
+    })()
+
+    try {
+      await pending
+    }
+    finally {
+      pending = null
+    }
+  }
+
+  const release = async (): Promise<void> => {
+    wanted = false
+    const s = sentinel
+    sentinel = null
+    active.value = false
+    if (s) await s.release().catch(() => {})
+  }
+
+  const onVisibilityChange = () => {
+    if (sentinel?.released === true) {
+      sentinel = null
+      active.value = false
+    }
+    const held = sentinel !== null && sentinel.released !== true
+    if (!shouldReacquire(wanted, isDocumentVisible(visibility), held)) return
+    // Refus possible (batterie faible, iframe…) : la prochaine visibilité réessaiera.
+    void request().catch(() => {})
+  }
+
+  visibility?.addEventListener("visibilitychange", onVisibilityChange)
+
+  return reactive({
+    get isActive() {
+      return active.value
+    },
+    get isCapable() {
+      return capable.value
+    },
+    request,
+    release,
+    destroy: () => {
+      visibility?.removeEventListener?.("visibilitychange", onVisibilityChange)
+    },
+  })
+}
+
+/** Singleton exposé sous `$q.wakeLock` (et importable directement depuis `@dnax/ui`). */
+export const wakeLock: QWakeLock = createWakeLock()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnax/ui",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "module": "index.ts",
   "description": "UI design System",
   "type": "module",

package/runtime.ts

@@ -39,6 +39,13 @@ export {
   useDialogPluginComponent,
   useBottomSheetPluginComponent,
 } from "./lib/q"
+// `$q.network` (état de connexion réactif) — accessible aussi par import direct,
+// sans évaluer le barrel ni les composants.
+export { network, createNetwork } from "./lib/network"
+export type { QNetwork, NetworkOptions } from "./lib/network"
+// `$q.wakeLock` (écran allumé) — Screen Wake Lock API.
+export { wakeLock, createWakeLock } from "./lib/wakeLock"
+export type { QWakeLock, WakeLockOptions } from "./lib/wakeLock"
 
 // — Providers de `$q` (montés au boot par l'app hôte) —
 export { default as QDialogProvider } from "./components/QDialogProvider.vue"

package/styles/main.css

@@ -831,6 +831,144 @@ html.dark body {
   align-items: stretch;
 }
 
+/* Flèches de défilement (`show-arrows`, comportement Quasar) : le contenu devient
+   défilable (barre de défilement masquée, le défilement est piloté par les flèches).
+   `scroll-padding` : le focus / `scrollIntoView` ne colle pas un onglet sous une flèche. */
+.q-tabs--arrows .q-tabs__content {
+  --q-tabs-fade-start: 0px;
+  --q-tabs-fade-end: 0px;
+
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+  scroll-padding-inline: 48px;
+  /* Fondu sous les flèches : masque **alpha** (transparent → blanc opaque). Le blanc est
+     opaque en mode `alpha` **et** `luminance` (ancien WebKit), et un masque ne dépend
+     d'aucune couleur de thème : le rendu est **identique en clair et en sombre** (contrairement
+     à un dégradé `--card` qui supposerait la couleur de surface du parent).
+     Le côté déjà entièrement visible garde `--q-tabs-fade-*: 0px` → aucun fondu. */
+  -webkit-mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    #fff var(--q-tabs-fade-start),
+    #fff calc(100% - var(--q-tabs-fade-end)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    #fff var(--q-tabs-fade-start),
+    #fff calc(100% - var(--q-tabs-fade-end)),
+    transparent 100%
+  );
+}
+
+/* Côtés à fondre — posés par le composant d'après les mesures de défilement
+   (`tabArrowState`) : à droite tant qu'il reste du contenu, à gauche dès qu'on a défilé. */
+.q-tabs--arrows.q-tabs--scroll-start .q-tabs__content {
+  --q-tabs-fade-start: 48px;
+}
+
+.q-tabs--arrows.q-tabs--scroll-end .q-tabs__content {
+  --q-tabs-fade-end: 48px;
+}
+
+.q-tabs--arrows .q-tabs__content::-webkit-scrollbar {
+  display: none;
+}
+
+.q-tabs--vertical.q-tabs--arrows .q-tabs__content {
+  overflow-x: hidden;
+  overflow-y: auto;
+  scroll-padding-inline: 0;
+  scroll-padding-block: 40px;
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #fff var(--q-tabs-fade-start),
+    #fff calc(100% - var(--q-tabs-fade-end)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #fff var(--q-tabs-fade-start),
+    #fff calc(100% - var(--q-tabs-fade-end)),
+    transparent 100%
+  );
+}
+
+.q-tabs--vertical.q-tabs--arrows.q-tabs--scroll-start .q-tabs__content {
+  --q-tabs-fade-start: 40px;
+}
+
+.q-tabs--vertical.q-tabs--arrows.q-tabs--scroll-end .q-tabs__content {
+  --q-tabs-fade-end: 40px;
+}
+
+/* Bouton **circulaire en surimpression** : les onglets défilent dessous. */
+.q-tabs__arrow {
+  position: absolute;
+  top: 50%;
+  z-index: 2;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 50%;
+  background-color: var(--card, #fff);
+  color: inherit;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.12);
+  cursor: pointer;
+  transform: translateY(-50%);
+  transition:
+    opacity 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.q-tabs__arrow--start {
+  left: 8px;
+}
+
+.q-tabs__arrow--end {
+  right: 8px;
+}
+
+.q-tabs__arrow:hover:not(:disabled) {
+  background-color: var(--muted, rgb(0 0 0 / 0.04));
+}
+
+/* Côté sans défilement possible : flèche **estompée** (toujours visible, comme la référence). */
+.q-tabs__arrow:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+
+.q-tabs__arrow svg {
+  width: 16px;
+  height: 16px;
+}
+
+/* Vertical : flèches en haut / en bas, centrées horizontalement. */
+.q-tabs--vertical .q-tabs__arrow {
+  top: auto;
+  left: 50%;
+  right: auto;
+  transform: translateX(-50%);
+}
+
+.q-tabs--vertical .q-tabs__arrow--start {
+  top: 8px;
+}
+
+.q-tabs--vertical .q-tabs__arrow--end {
+  bottom: 8px;
+}
+
 .q-tabs--dense {
   --q-tabs-h: 32px;
 }
@@ -841,10 +979,14 @@ html.dark body {
 
 .q-tabs--center .q-tabs__content {
   justify-content: center;
+  /* `safe` : en cas de débordement, retombe sur `flex-start` au lieu de rendre le
+     début inaccessible au défilement (bug classique du flex centré + overflow). */
+  justify-content: safe center;
 }
 
 .q-tabs--right .q-tabs__content {
   justify-content: flex-end;
+  justify-content: safe flex-end;
 }
 
 .q-tabs--justify .q-tab {
@@ -6063,7 +6205,7 @@ a.q-breadcrumbs__el:hover {
   background-color: var(--primary);
 }
 
-/* — raccourci « Today » (prop `today-btn`) : bord à bord dans le panneau — */
+/* — raccourci « aujourd'hui » (prop `today-btn`) : bord à bord dans le panneau — */
 .q-date-calendar__footer {
   display: flex;
   justify-content: flex-end;