@jant/core 0.5.1 → 0.5.3

package/src/client/__tests__/slash-discovery.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __testOnly,
+  hideSlashCommandHint,
+  markSlashCommandDiscovered,
+  scheduleSlashCommandHint,
+} from "../slash-discovery.js";
+
+function createEditorHost(discovered = false): HTMLElement {
+  document.body.innerHTML = `
+    <jant-compose-editor data-slash-command-discovered="${discovered ? "true" : "false"}">
+      <div class="compose-tiptap-body"></div>
+      <span class="compose-slash-discovery-hint" aria-hidden="true">Type / for commands</span>
+    </jant-compose-editor>
+  `;
+
+  return document.querySelector<HTMLElement>(
+    "jant-compose-editor",
+  ) as HTMLElement;
+}
+
+describe("slash discovery", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.useFakeTimers();
+    globalThis.localStorage.clear();
+    __testOnly.reset();
+    vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: true }));
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("shows the hint after the delay and records one exposure per page", () => {
+    const host = createEditorHost();
+
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      true,
+    );
+    expect(__testOnly.readState()).toMatchObject({
+      shownCount: 1,
+      completed: false,
+    });
+
+    // No auto-fade — the hint stays visible until something explicitly hides it.
+    vi.advanceTimersByTime(5000);
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      true,
+    );
+
+    hideSlashCommandHint(host);
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      false,
+    );
+
+    // Refocusing during the same page load shows the hint again
+    // without bumping the persisted shownCount.
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      true,
+    );
+    expect(__testOnly.readState().shownCount).toBe(1);
+  });
+
+  it("hides the hint immediately when called", () => {
+    const host = createEditorHost();
+
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      true,
+    );
+
+    hideSlashCommandHint(host);
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      false,
+    );
+  });
+
+  it("does not show the hint after the local max has been reached", () => {
+    const host = createEditorHost();
+    globalThis.localStorage.setItem(
+      __testOnly.SLASH_DISCOVERY_STORAGE_KEY,
+      JSON.stringify({
+        shownCount: __testOnly.SLASH_HINT_MAX_SHOW_COUNT,
+        completed: false,
+      }),
+    );
+
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      false,
+    );
+  });
+
+  it("does not show the hint when the DB flag is already set", () => {
+    const host = createEditorHost(true);
+
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      false,
+    );
+  });
+
+  it("does not show the hint on mobile widths", () => {
+    vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: false }));
+    const host = createEditorHost();
+
+    scheduleSlashCommandHint(host);
+    vi.advanceTimersByTime(__testOnly.SLASH_HINT_DELAY_MS);
+
+    expect(host.classList.contains(__testOnly.SLASH_HINT_VISIBLE_CLASS)).toBe(
+      false,
+    );
+  });
+
+  it("marks the slash command as completed locally and syncs to the server", async () => {
+    const host = createEditorHost();
+
+    markSlashCommandDiscovered();
+    await Promise.resolve();
+
+    expect(__testOnly.readState()).toMatchObject({
+      shownCount: __testOnly.SLASH_HINT_MAX_SHOW_COUNT,
+      completed: true,
+    });
+    expect(host.dataset.slashCommandDiscovered).toBe("true");
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      __testOnly.SLASH_DISCOVERY_API_PATH,
+      expect.objectContaining({
+        method: "POST",
+        credentials: "same-origin",
+      }),
+    );
+  });
+});

package/src/client/components/__tests__/jant-compose-dialog.test.ts

@@ -230,6 +230,7 @@ const labels: ComposeLabels = {
   showMore: "Show more",
   showLess: "Show less",
   newThread: "New Thread",
+  slashHint: "Type / for commands",
   collectionFormLabels: {
     titleLabel: "Title",
     titlePlaceholder: "My Collection",

package/src/client/components/__tests__/jant-compose-editor.test.ts

@@ -264,6 +264,7 @@ const labels: ComposeLabels = {
   showMore: "Show more",
   showLess: "Show less",
   newThread: "New Thread",
+  slashHint: "Type / for commands",
   collectionFormLabels: {
     titleLabel: "Title",
     titlePlaceholder: "My Collection",

package/src/client/components/compose-types.ts

@@ -214,6 +214,7 @@ export interface ComposeLabels {
   showMore: string;
   showLess: string;
   newThread: string;
+  slashHint: string;
   collectionFormLabels: CollectionFormLabels;
 }
 

package/src/client/components/jant-compose-dialog.ts

@@ -534,6 +534,10 @@ export class JantComposeDialog extends LitElement {
     pageMode: { type: Boolean, attribute: "page-mode" },
     closeHref: { type: String, attribute: "close-href" },
     autoRestoreDraft: { type: Boolean, attribute: "auto-restore-draft" },
+    slashCommandDiscovered: {
+      type: Boolean,
+      attribute: "slash-command-discovered",
+    },
     _format: { state: true },
     _status: { state: true },
     _loading: { state: true },
@@ -578,6 +582,7 @@ export class JantComposeDialog extends LitElement {
   declare pageMode: boolean;
   declare closeHref: string;
   declare autoRestoreDraft: boolean;
+  declare slashCommandDiscovered: boolean;
   declare _format: ComposeFormat;
   declare _status: "published" | "draft";
   declare _loading: boolean;
@@ -665,6 +670,7 @@ export class JantComposeDialog extends LitElement {
     this.pageMode = false;
     this.closeHref = "/";
     this.autoRestoreDraft = false;
+    this.slashCommandDiscovered = false;
     this._format = "note";
     this._status = "published";
     this._loading = false;
@@ -4121,7 +4127,9 @@ export class JantComposeDialog extends LitElement {
 
   private _getSubmitLabel(): string {
     if (this._editPostId) return this.labels.update;
-    if (this._replyToId) return this.labels.reply;
+    if (this._replyToId) {
+      return this._quietReply ? this.labels.quietReplyLabel : this.labels.reply;
+    }
     if (this._visibility === "latest_hidden") {
       return this.labels.postHiddenFromLatest;
     }
@@ -5009,16 +5017,35 @@ export class JantComposeDialog extends LitElement {
     `;
   }
 
-  private _renderHideFromLatestQuickToggleRow() {
-    if (this._visibilityLocked) return nothing;
-    if (this._visibility === "private") return nothing;
+  private _renderQuickActionsRow() {
+    const hideFromLatest = this._renderHideFromLatestQuickToggle();
+    const quietReply = this._renderQuietReplyQuickToggle();
+    if (hideFromLatest === nothing && quietReply === nothing) return nothing;
     return html`
       <div class="compose-quick-actions-row">
-        ${this._renderHideFromLatestQuickToggle()}
+        ${hideFromLatest} ${quietReply}
       </div>
     `;
   }
 
+  private _renderQuietReplyQuickToggle() {
+    if (!this._replyToId) return nothing;
+    return html`
+      <label class="compose-publish-quick-toggle">
+        <input
+          type="checkbox"
+          class="input compose-publish-quick-toggle-input"
+          .checked=${this._quietReply}
+          ?disabled=${this._loading}
+          @change=${(e: Event) => {
+            this._quietReply = (e.target as HTMLInputElement).checked;
+          }}
+        />
+        <span>${this.labels.quietReplyLabel}</span>
+      </label>
+    `;
+  }
+
   private _renderHideFromLatestQuickToggle() {
     if (this._visibilityLocked) return nothing;
     if (this._visibility === "private") return nothing;
@@ -5283,6 +5310,7 @@ export class JantComposeDialog extends LitElement {
           .uploadMaxFileSize=${this.uploadMaxFileSize}
           .threadItem=${true}
           .removable=${showRemove}
+          .slashCommandDiscovered=${this.slashCommandDiscovered}
           data-thread-id=${item.id}
         ></jant-compose-editor>
       </div>
@@ -5387,6 +5415,7 @@ export class JantComposeDialog extends LitElement {
       .format=${this._format}
       .labels=${this.labels}
       .uploadMaxFileSize=${this.uploadMaxFileSize}
+      .slashCommandDiscovered=${this.slashCommandDiscovered}
     ></jant-compose-editor>`;
 
     return html`
@@ -5431,7 +5460,7 @@ export class JantComposeDialog extends LitElement {
                 ${this._renderCollectionSelector()}
                 ${this._renderPublishButton()}
               </div>
-              ${this._renderHideFromLatestQuickToggleRow()}`}
+              ${this._renderQuickActionsRow()}`}
         ${this._renderMobilePublishPanel()} ${this._renderAttachedPanel()}
         ${this._renderAltPanel()} ${this._renderDraftsPanel()}
         ${this._renderConfirmPanel()}

package/src/client/components/jant-compose-editor.ts

@@ -48,6 +48,11 @@ import {
 } from "../tiptap/inline-image-upload.js";
 import { isSafeAbsoluteUrl } from "../../lib/url.js";
 import { randomUUID } from "../random-uuid.js";
+import {
+  hideSlashCommandHint,
+  markSlashCommandDiscovered,
+  scheduleSlashCommandHint,
+} from "../slash-discovery.js";
 
 interface ComposeFilePickerCloseDetail {
   cancelled: boolean;
@@ -172,6 +177,7 @@ export class JantComposeEditor extends LitElement {
     uploadMaxFileSize: { type: Number },
     threadItem: { type: Boolean, attribute: "thread-item" },
     removable: { type: Boolean },
+    slashCommandDiscovered: { type: Boolean },
     _title: { state: true },
     _bodyJson: { state: true },
     _url: { state: true },
@@ -196,6 +202,7 @@ export class JantComposeEditor extends LitElement {
   declare uploadMaxFileSize: number;
   declare threadItem: boolean;
   declare removable: boolean;
+  declare slashCommandDiscovered: boolean;
   declare _title: string;
   declare _bodyJson: JSONContent | null;
   declare _url: string;
@@ -242,6 +249,7 @@ export class JantComposeEditor extends LitElement {
     this.uploadMaxFileSize = 500;
     this.threadItem = false;
     this.removable = false;
+    this.slashCommandDiscovered = false;
     this._title = "";
     this._bodyJson = null;
     this._url = "";
@@ -264,6 +272,10 @@ export class JantComposeEditor extends LitElement {
   connectedCallback() {
     super.connectedCallback();
     document.addEventListener("jant:slash-image", this._onSlashImage);
+    document.addEventListener(
+      "jant:slash-command-discovered",
+      this._onSlashCommandDiscovered,
+    );
   }
 
   disconnectedCallback() {
@@ -274,13 +286,22 @@ export class JantComposeEditor extends LitElement {
     this.#sortable?.destroy();
     this.#sortable = null;
     document.removeEventListener("jant:slash-image", this._onSlashImage);
+    document.removeEventListener(
+      "jant:slash-command-discovered",
+      this._onSlashCommandDiscovered,
+    );
     document.removeEventListener("click", this._onDocClickBound);
+    hideSlashCommandHint(this);
     this._emojiContainer?.remove();
     this._emojiPickerEl = null;
     this._filePickerCleanup?.();
     this._filePickerCleanup = null;
   }
 
+  private _onSlashCommandDiscovered = () => {
+    markSlashCommandDiscovered();
+  };
+
   private _onSlashImage = () => {
     // Skip when fullscreen is open — it has its own handler
     if (document.querySelector(".compose-fullscreen-dialog[open]")) return;
@@ -686,6 +707,10 @@ export class JantComposeEditor extends LitElement {
     const container = this.querySelector<HTMLElement>(".compose-tiptap-body");
     if (!container || this._editor) return;
 
+    this.dataset.slashCommandDiscovered = this.slashCommandDiscovered
+      ? "true"
+      : "false";
+
     this._editor = createTiptapEditor({
       element: container,
       placeholder:
@@ -697,9 +722,13 @@ export class JantComposeEditor extends LitElement {
       onUpdate: (json) => {
         this._bodyJson = json;
         this._ensureScrollBuffer();
+        hideSlashCommandHint(this);
       },
       onFocus: () => {
         this._lastFocusedField = null;
+        if (this._editor?.isEmpty) {
+          scheduleSlashCommandHint(this);
+        }
       },
       onSelectionUpdate: (selection) => {
         this._lastEditorSelection = selection;
@@ -1655,7 +1684,12 @@ export class JantComposeEditor extends LitElement {
               </div>
             `
           : nothing}
-        <div class="compose-tiptap-body"></div>
+        <div class="compose-tiptap-wrap">
+          <div class="compose-tiptap-body"></div>
+          <span class="compose-slash-discovery-hint" aria-hidden="true">
+            ${this.labels.slashHint}
+          </span>
+        </div>
       </div>
     `;
   }
@@ -1723,9 +1757,14 @@ export class JantComposeEditor extends LitElement {
             </p>`
           : nothing}
         <div class="compose-divider"></div>
-        <div
-          class="compose-tiptap-body compose-tiptap-thoughts compose-tiptap-link"
-        ></div>
+        <div class="compose-tiptap-wrap">
+          <div
+            class="compose-tiptap-body compose-tiptap-thoughts compose-tiptap-link"
+          ></div>
+          <span class="compose-slash-discovery-hint" aria-hidden="true">
+            ${this.labels.slashHint}
+          </span>
+        </div>
       </div>
     `;
   }
@@ -1789,9 +1828,14 @@ export class JantComposeEditor extends LitElement {
           class="compose-divider compose-divider-quote"
           aria-hidden="true"
         ></div>
-        <div
-          class="compose-tiptap-body compose-tiptap-thoughts compose-tiptap-thoughts-quote"
-        ></div>
+        <div class="compose-tiptap-wrap">
+          <div
+            class="compose-tiptap-body compose-tiptap-thoughts compose-tiptap-thoughts-quote"
+          ></div>
+          <span class="compose-slash-discovery-hint" aria-hidden="true">
+            ${this.labels.slashHint}
+          </span>
+        </div>
       </div>
     `;
   }

package/src/client/components/jant-media-lightbox.ts

@@ -280,46 +280,130 @@ export class JantMediaLightbox extends LitElement {
   #handleKeydown = (e: Event) => {
     const ke = e as globalThis.KeyboardEvent;
     const target = e.target as HTMLElement | null;
+
     if (ke.key === "Escape") {
       e.preventDefault();
       this.close();
       return;
     }
-    if (ke.key !== "ArrowLeft" && ke.key !== "ArrowRight") return;
 
-    // Let the progress slider's native arrow-key seeking through.
-    if (target?.classList.contains("media-lightbox-short-progress")) return;
+    // Don't hijack keys aimed at a focused control — the short-video progress
+    // slider, the mute/close/nav buttons, or the <video> itself (when focused,
+    // its native shortcuts already handle these keys). Let their native
+    // behavior run instead of double-handling.
+    if (
+      target instanceof HTMLInputElement ||
+      target instanceof HTMLButtonElement ||
+      target instanceof HTMLVideoElement
+    ) {
+      return;
+    }
 
-    // On videos, arrow keys scrub the playhead. Item switching happens via
-    // the on-screen prev/next buttons — matches YouTube/native player conventions.
     const currentImage = this._images[this._currentIndex];
-    if (currentImage?.mimeType?.startsWith("video/")) {
-      const video = this.querySelector<HTMLVideoElement>(
-        ".media-lightbox-video",
-      );
-      if (video) {
+    if (!currentImage?.mimeType?.startsWith("video/")) {
+      // Image galleries: arrow keys switch items.
+      if (ke.key === "ArrowLeft") {
+        e.preventDefault();
+        this.#prev();
+      } else if (ke.key === "ArrowRight") {
         e.preventDefault();
-        const step = 5;
-        const delta = ke.key === "ArrowLeft" ? -step : step;
-        const duration =
-          Number.isFinite(video.duration) && video.duration > 0
-            ? video.duration
-            : null;
-        const nextTime =
-          duration != null
-            ? Math.max(0, Math.min(video.currentTime + delta, duration))
-            : Math.max(0, video.currentTime + delta);
-        video.currentTime = nextTime;
-        this._videoCurrentTime = nextTime;
+        this.#next();
       }
       return;
     }
 
-    e.preventDefault();
-    if (ke.key === "ArrowLeft") this.#prev();
-    else this.#next();
+    const video = this.querySelector<HTMLVideoElement>(".media-lightbox-video");
+    if (video) this.#handleVideoKeydown(ke, video);
   };
 
+  // Video shortcuts — play/pause, seek, volume, mute, fullscreen — handled at
+  // the dialog level so they work regardless of what's focused. Item switching
+  // happens via the on-screen prev/next buttons, matching YouTube/native
+  // player conventions.
+  #handleVideoKeydown(ke: globalThis.KeyboardEvent, video: HTMLVideoElement) {
+    const duration =
+      Number.isFinite(video.duration) && video.duration > 0
+        ? video.duration
+        : null;
+    const seekTo = (time: number) => {
+      const next =
+        duration != null
+          ? Math.max(0, Math.min(time, duration))
+          : Math.max(0, time);
+      video.currentTime = next;
+      this._videoCurrentTime = next;
+    };
+    const key = ke.key;
+    const lower = key.toLowerCase();
+
+    if (key === " " || lower === "k") {
+      ke.preventDefault();
+      if (video.paused) void video.play().catch(() => {});
+      else video.pause();
+    } else if (key === "ArrowLeft") {
+      ke.preventDefault();
+      seekTo(video.currentTime - 5);
+    } else if (key === "ArrowRight") {
+      ke.preventDefault();
+      seekTo(video.currentTime + 5);
+    } else if (key === "Home") {
+      ke.preventDefault();
+      seekTo(0);
+    } else if (key === "End") {
+      if (duration != null) {
+        ke.preventDefault();
+        seekTo(duration);
+      }
+    } else if (key.length === 1 && key >= "0" && key <= "9") {
+      if (duration != null) {
+        ke.preventDefault();
+        seekTo((Number(key) / 10) * duration);
+      }
+    } else if (key === "ArrowUp") {
+      ke.preventDefault();
+      video.volume = Math.min(1, video.volume + 0.05);
+    } else if (key === "ArrowDown") {
+      ke.preventDefault();
+      video.volume = Math.max(0, video.volume - 0.05);
+    } else if (lower === "m") {
+      ke.preventDefault();
+      const muted = !video.muted;
+      video.muted = muted;
+      this._videoMuted = muted;
+    } else if (lower === "f") {
+      ke.preventDefault();
+      this.#toggleVideoFullscreen(video);
+    }
+  }
+
+  #toggleVideoFullscreen(video: HTMLVideoElement) {
+    const doc = document as globalThis.Document & {
+      webkitFullscreenElement?: globalThis.Element | null;
+      webkitExitFullscreen?: () => void;
+    };
+    const el = video as HTMLVideoElement & {
+      webkitRequestFullscreen?: () => void;
+      webkitEnterFullscreen?: () => void;
+    };
+
+    if (document.fullscreenElement ?? doc.webkitFullscreenElement) {
+      if (document.exitFullscreen) {
+        void document.exitFullscreen().catch(() => {});
+      } else {
+        doc.webkitExitFullscreen?.();
+      }
+      return;
+    }
+
+    if (video.requestFullscreen) {
+      void video.requestFullscreen().catch(() => {});
+    } else if (el.webkitRequestFullscreen) {
+      el.webkitRequestFullscreen();
+    } else if (el.webkitEnterFullscreen) {
+      el.webkitEnterFullscreen();
+    }
+  }
+
   #handleDialogClick = (e: Event) => {
     const target = e.target as HTMLElement;
     // Close on backdrop click (dialog itself or the content wrapper, not media/buttons)
@@ -365,24 +449,23 @@ export class JantMediaLightbox extends LitElement {
     this.querySelector<HTMLVideoElement>(".media-lightbox-video")?.pause();
   }
 
-  // Focus the active video so space/native shortcuts work without an extra
-  // click. Falls back to the content wrapper for images — focusing the close
-  // button would show a focus ring during arrow-key nav.
+  // Move focus to the content wrapper on open / item change — not the close
+  // button (its focus ring would show during arrow-key nav) and not the
+  // <video> (a focused <video> routes keydown to its own native handler,
+  // bypassing the dialog-level shortcuts in #handleVideoKeydown).
   #focusCurrentMedia() {
-    const currentImage = this._images[this._currentIndex];
-    const isVideo = currentImage?.mimeType?.startsWith("video/");
-    if (isVideo) {
-      const video = this.querySelector<HTMLVideoElement>(
-        ".media-lightbox-video",
-      );
-      if (video) {
-        video.focus();
-        return;
-      }
-    }
     this.querySelector<HTMLElement>(".media-lightbox-content")?.focus();
   }
 
+  // Browsers focus a <video> when it's clicked. Bounce focus back to the
+  // content wrapper so keydown keeps reaching the dialog-level shortcut
+  // handler instead of the video's native key handling.
+  #handleVideoFocus = () => {
+    this.querySelector<HTMLElement>(".media-lightbox-content")?.focus({
+      preventScroll: true,
+    });
+  };
+
   #resetShortVideoState(image?: LightboxImage) {
     this._videoCurrentTime = 0;
     this._videoDuration =
@@ -543,6 +626,7 @@ export class JantMediaLightbox extends LitElement {
                       playsinline
                       loop
                       ?muted=${this._videoMuted}
+                      @focus=${this.#handleVideoFocus}
                       @loadedmetadata=${this.#handleShortVideoLoadedMetadata}
                       @timeupdate=${this.#handleShortVideoTimeUpdate}
                     ></video>
@@ -596,6 +680,7 @@ export class JantMediaLightbox extends LitElement {
                     controls
                     autoplay
                     playsinline
+                    @focus=${this.#handleVideoFocus}
                   ></video>`
               : html`<img
                   class=${`media-lightbox-img${isScrollableImage ? " media-lightbox-img-scroll" : ""}`}

package/src/client/slash-discovery-bridge.ts

@@ -0,0 +1,9 @@
+import { initSlashCommandDiscovery } from "./slash-discovery.js";
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", () => {
+    initSlashCommandDiscovery();
+  });
+} else {
+  initSlashCommandDiscovery();
+}