@lapismd/design-core 0.1.0

package/src/shared/workspace/plugins/f-mode/FModeOverlay.css

@@ -0,0 +1,158 @@
+.ui-workspace-fmode {
+  --ui-workspace-fmode-accent: var(
+    --ui-workspace-fmode-default-accent,
+    var(--ui-workspace-accent)
+  );
+  --ui-workspace-fmode-surface: color-mix(
+    in srgb,
+    var(--ui-workspace-background) 92%,
+    black 8%
+  );
+  --ui-workspace-fmode-surface-strong: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-accent) 18%,
+    var(--ui-workspace-fmode-surface)
+  );
+  --ui-workspace-fmode-border: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-accent) 40%,
+    transparent
+  );
+  pointer-events: none;
+  position: fixed;
+  z-index: var(--ui-workspace-overlay-z-index);
+  inset: 0;
+  color: var(--ui-workspace-foreground);
+}
+
+.ui-workspace-fmode__hud,
+.ui-workspace-fmode__hint {
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid var(--ui-workspace-fmode-border);
+  color: var(--ui-workspace-foreground);
+  background: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-surface) 94%,
+    transparent
+  );
+  box-shadow:
+    0 18px 40px color-mix(in srgb, black 20%, transparent),
+    0 2px 8px color-mix(in srgb, black 12%, transparent);
+  backdrop-filter: blur(18px);
+}
+
+.ui-workspace-fmode__hud {
+  position: fixed;
+  top: 1rem;
+  right: 1rem;
+  gap: 0.75rem;
+  border-radius: 999px;
+  padding: 0.6rem 0.9rem;
+}
+
+.ui-workspace-fmode__query {
+  font-family: var(
+    --ui-workspace-fmode-font-mono,
+    var(--ui-workspace-font-mono)
+  );
+  font-size: 0.8rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.ui-workspace-fmode__summary {
+  color: var(--ui-workspace-muted-foreground);
+  font-size: 0.75rem;
+}
+
+.ui-workspace-fmode__hint {
+  position: fixed;
+  max-width: min(22rem, calc(100vw - 1rem));
+  gap: 0.5rem;
+  border-radius: var(--ui-workspace-radius-large);
+  padding: 0.35rem 0.55rem;
+}
+
+.ui-workspace-fmode__hint[hidden] {
+  display: none;
+}
+
+.ui-workspace-fmode__hint--exact {
+  border-color: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-accent) 65%,
+    transparent
+  );
+  background: var(--ui-workspace-fmode-surface-strong);
+  transform: scale(1.02);
+}
+
+.ui-workspace-fmode__hint-code {
+  border-radius: var(--ui-workspace-radius-small);
+  padding: 0.125rem 0.25rem;
+  color: var(--ui-workspace-foreground);
+  background: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-accent) 18%,
+    transparent
+  );
+  font-family: var(
+    --ui-workspace-fmode-font-mono,
+    var(--ui-workspace-font-mono)
+  );
+  font-size: 0.72rem;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.ui-workspace-fmode__hint-label,
+.ui-workspace-fmode__hint-description {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ui-workspace-fmode__hint-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+}
+
+.ui-workspace-fmode__hint-description {
+  color: var(--ui-workspace-muted-foreground);
+  font-size: 0.72rem;
+}
+
+.ui-workspace-fmode[data-fmode-hud-mode="minimal"] .ui-workspace-fmode__hint {
+  max-width: none;
+  gap: 0;
+  border: 0;
+  border-radius: 0;
+  padding: 0;
+  box-shadow: none;
+  backdrop-filter: none;
+}
+
+.ui-workspace-fmode[data-fmode-hud-mode="minimal"]
+  .ui-workspace-fmode__hint-code {
+  border: 1px solid var(--ui-workspace-fmode-border);
+  padding: 0.1rem 0.26rem;
+  background: color-mix(
+    in srgb,
+    var(--ui-workspace-fmode-accent) 24%,
+    var(--ui-workspace-background)
+  );
+  font-size: 0.5rem;
+  letter-spacing: 0.06em;
+}
+
+.ui-workspace-fmode--invalid .ui-workspace-fmode__hud {
+  border-color: color-mix(
+    in srgb,
+    var(--ui-workspace-destructive) 72%,
+    transparent
+  );
+}

package/src/shared/workspace/plugins/f-mode/FModeOverlay.svelte

@@ -0,0 +1,210 @@
+<script lang="ts">
+  import type { AppShellOverlayComponentProps } from "../../core/app-shell-ui-registry.svelte.js";
+  import type { FModeEntry } from "./hint-labels.js";
+  import type { FModeSession } from "./f-mode-session.svelte.js";
+  import type { FModeHintTarget } from "./types.js";
+  import "./FModeOverlay.css";
+
+  let {
+    session,
+  }: AppShellOverlayComponentProps & {
+    session: FModeSession;
+  } = $props();
+
+  let host = $state<HTMLDivElement | null>(null);
+  let positions = $state<
+    Record<string, { left: number; top: number; placement: string }>
+  >({});
+  let invalid = $state(false);
+  let layoutFrame: number | null = null;
+  let invalidTimer: ReturnType<typeof setTimeout> | null = null;
+  let visibleEntries = $derived(session.visibleEntries);
+  let visibleIds = $derived(
+    new Set(visibleEntries.map((entry) => entry.target.id)),
+  );
+
+  function clips(value: string): boolean {
+    return ["auto", "clip", "hidden", "overlay", "scroll"].includes(value);
+  }
+
+  function visibleTargetRect(element: HTMLElement): DOMRect | null {
+    const view = element.ownerDocument.defaultView;
+    if (!view) return null;
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) return null;
+    let left = Math.max(0, rect.left);
+    let top = Math.max(0, rect.top);
+    let right = Math.min(view.innerWidth, rect.right);
+    let bottom = Math.min(view.innerHeight, rect.bottom);
+    for (
+      let current = element.parentElement;
+      current && current !== element.ownerDocument.body;
+      current = current.parentElement
+    ) {
+      const style = view.getComputedStyle(current);
+      const ancestorRect = current.getBoundingClientRect();
+      if (clips(style.overflowX)) {
+        left = Math.max(left, ancestorRect.left);
+        right = Math.min(right, ancestorRect.right);
+      }
+      if (clips(style.overflowY)) {
+        top = Math.max(top, ancestorRect.top);
+        bottom = Math.min(bottom, ancestorRect.bottom);
+      }
+      if (right <= left || bottom <= top) return null;
+    }
+    return right > left && bottom > top
+      ? new DOMRect(left, top, right - left, bottom - top)
+      : null;
+  }
+
+  function layoutBadges(): void {
+    if (!host) return;
+    const view = host.ownerDocument.defaultView;
+    if (!view) return;
+    const next: typeof positions = {};
+    for (const entry of session.entries) {
+      if (!visibleIds.has(entry.target.id)) continue;
+      const rect = visibleTargetRect(entry.target.element);
+      const badge = host.querySelector<HTMLElement>(
+        `[data-fmode-target-id="${CSS.escape(entry.target.id)}"]`,
+      );
+      if (!rect || !badge) continue;
+      const badgeRect = badge.getBoundingClientRect();
+      const padding = 8;
+      const preferredLeft = rect.right - badgeRect.width;
+      const preferredTop = rect.bottom - badgeRect.height;
+      const left = Math.min(
+        Math.max(Math.round(preferredLeft), padding),
+        Math.max(padding, view.innerWidth - badgeRect.width - padding),
+      );
+      const top = Math.min(
+        Math.max(Math.round(preferredTop), padding),
+        Math.max(padding, view.innerHeight - badgeRect.height - padding),
+      );
+      next[entry.target.id] = {
+        left,
+        top,
+        placement: `${top < preferredTop ? "top" : "bottom"}-${left < preferredLeft ? "left" : "right"}`,
+      };
+    }
+    positions = next;
+  }
+
+  function scheduleLayout(): void {
+    if (!host || layoutFrame !== null) return;
+    const view = host.ownerDocument.defaultView;
+    if (!view) return;
+    layoutFrame = view.requestAnimationFrame(() => {
+      layoutFrame = null;
+      layoutBadges();
+    });
+  }
+
+  function styleFor(entry: FModeEntry<FModeHintTarget>): string {
+    const position = positions[entry.target.id];
+    return position
+      ? `left:${position.left}px;top:${position.top}px;`
+      : "visibility:hidden;";
+  }
+
+  $effect(() => {
+    session.query;
+    session.entries;
+    if (session.active) scheduleLayout();
+  });
+
+  $effect(() => {
+    const sequence = session.invalidSequence;
+    if (!sequence) return;
+    invalid = false;
+    requestAnimationFrame(() => {
+      invalid = true;
+      if (invalidTimer) clearTimeout(invalidTimer);
+      invalidTimer = setTimeout(() => (invalid = false), 180);
+    });
+  });
+
+  $effect(() => {
+    if (!session.active || !host) return;
+    const document = host.ownerDocument;
+    const view = document.defaultView;
+    const update = () => scheduleLayout();
+    document.addEventListener("scroll", update, true);
+    view?.addEventListener("resize", update);
+    const resizeObserver =
+      typeof ResizeObserver === "function" ? new ResizeObserver(update) : null;
+    resizeObserver?.observe(document.body);
+    for (const entry of session.entries) {
+      resizeObserver?.observe(entry.target.element);
+    }
+    scheduleLayout();
+    return () => {
+      document.removeEventListener("scroll", update, true);
+      view?.removeEventListener("resize", update);
+      resizeObserver?.disconnect();
+      if (layoutFrame !== null) view?.cancelAnimationFrame(layoutFrame);
+      layoutFrame = null;
+    };
+  });
+</script>
+
+{#if session.active && session.settings}
+  <div
+    bind:this={host}
+    class="ui-workspace-fmode"
+    class:ui-workspace-fmode--invalid={invalid}
+    data-ui-component="workspace-f-mode"
+    data-ui-part="overlay"
+    data-fmode-root
+    data-fmode-hud-mode={session.settings.hudMode}
+    style={session.settings.accentColor
+      ? `--ui-workspace-fmode-accent:${session.settings.accentColor};`
+      : undefined}
+  >
+    <div
+      class="ui-workspace-fmode__hud"
+      data-ui-part="hud"
+      hidden={session.settings.hudMode === "minimal"}
+    >
+      <span class="ui-workspace-fmode__query">
+        {session.query ? session.query.toUpperCase() : "Type a hint"}
+      </span>
+      <span
+        class="ui-workspace-fmode__summary"
+        hidden={session.settings.hudMode !== "detailed"}
+      >
+        {session.query
+          ? `${visibleEntries.length} matches`
+          : `${session.entries.length} targets`}
+      </span>
+    </div>
+    {#each session.entries as entry (entry.target.id)}
+      <div
+        class="ui-workspace-fmode__hint"
+        class:ui-workspace-fmode__hint--exact={session.exactEntry?.target.id ===
+          entry.target.id}
+        hidden={!visibleIds.has(entry.target.id)}
+        data-ui-part="hint"
+        data-fmode-hint={entry.hint}
+        data-fmode-target-id={entry.target.id}
+        data-fmode-placement={positions[entry.target.id]?.placement}
+        style={styleFor(entry)}
+      >
+        <span class="ui-workspace-fmode__hint-code">
+          {entry.hint.toUpperCase()}
+        </span>
+        {#if session.settings.hudMode !== "minimal" && session.settings.showTargetLabels}
+          <span class="ui-workspace-fmode__hint-label">
+            {entry.target.label}
+          </span>
+          {#if session.settings.showTargetDescriptions && entry.target.description}
+            <span class="ui-workspace-fmode__hint-description">
+              {entry.target.description}
+            </span>
+          {/if}
+        {/if}
+      </div>
+    {/each}
+  </div>
+{/if}

package/src/shared/workspace/plugins/f-mode/f-mode-plugin.ts

@@ -0,0 +1,152 @@
+import {
+  AppShellPlugin,
+  CommandKeymapScope,
+  Notice,
+  type AppShellPluginDescriptor,
+} from "../../core/index.js";
+import FModeOverlay from "./FModeOverlay.svelte";
+import { FModeSession } from "./f-mode-session.svelte.js";
+import { normalizeFModeKey } from "./hint-labels.js";
+import {
+  createFModeSettingsSection,
+  createFModeTargetGroups,
+  filterFModeTargets,
+  readFModeSettings,
+} from "./settings.js";
+import type {
+  FModeHintTarget,
+  FModePluginOptions,
+  FModeTargetGroupDefinition,
+} from "./types.js";
+
+const DEFAULT_HOTKEYS = [{ modifiers: ["Mod", "Shift"], key: "F" }] as const;
+
+interface FModeRuntimeOptions {
+  hotkeys: FModePluginOptions["hotkeys"];
+  targetGroups: FModeTargetGroupDefinition[];
+}
+
+class FModeAppShellPlugin extends AppShellPlugin<FModeRuntimeOptions> {
+  readonly #session = new FModeSession();
+  readonly #groups: FModeTargetGroupDefinition[];
+
+  constructor(
+    app: ConstructorParameters<typeof AppShellPlugin>[0],
+    id: string,
+    options: FModeRuntimeOptions,
+  ) {
+    super(app, id, options);
+    this.#groups = createFModeTargetGroups(options.targetGroups);
+  }
+
+  onload(): void {
+    this.registerSettingsSection(createFModeSettingsSection(this.#groups));
+    this.registerOverlay({
+      id: "fmode:overlay",
+      component: FModeOverlay,
+      props: { session: this.#session },
+      priority: 100,
+    });
+    const scope = new CommandKeymapScope();
+    scope.registerAny((event) => {
+      if (!this.#session.active) return false;
+      event.preventDefault();
+      event.stopPropagation();
+      this.#handleSessionKeydown(event);
+      return true;
+    });
+    this.pushKeymapScope(scope);
+    this.addCommand({
+      id: "toggle-fmode",
+      title: "Toggle F-Mode",
+      category: "Navigation",
+      icon: "scan-search",
+      hotkeys:
+        this.options.hotkeys ??
+        DEFAULT_HOTKEYS.map((entry) => ({
+          modifiers: [...entry.modifiers],
+          key: entry.key,
+        })),
+      callback: () => this.#toggleSession(),
+    });
+    this.register(() => this.#session.close());
+  }
+
+  #toggleSession(): void {
+    if (this.#session.active) {
+      this.#session.close();
+      return;
+    }
+    const settings = readFModeSettings(this.app, this.#groups);
+    const targets = filterFModeTargets(
+      this.app.ui.getVisibleHintTargets(),
+      settings.enabledSurfaces,
+    );
+    if (targets.length === 0) {
+      new Notice(this.app, "No hint targets available");
+      return;
+    }
+    this.#session.open(targets, settings);
+  }
+
+  #handleSessionKeydown(event: KeyboardEvent): void {
+    if (event.isComposing) return;
+    if (event.key === "Escape") {
+      this.#session.close();
+      return;
+    }
+    if (event.key === "Backspace") {
+      this.#session.backspace();
+      return;
+    }
+    const key = normalizeFModeKey(event.key);
+    if (!key) return;
+    const result = this.#session.advance(key);
+    if (
+      !result.accepted &&
+      this.#session.settings?.invalidInputBehavior === "close"
+    ) {
+      this.#session.close();
+      return;
+    }
+    if (result.matchedTarget) {
+      this.#session.close();
+      this.#activateTarget(result.matchedTarget);
+    }
+  }
+
+  #activateTarget(target: FModeHintTarget): void {
+    if (target.commandId || target.action === "command") {
+      if (!target.commandId) return;
+      void this.app.commands.execute(target.commandId).then((executed) => {
+        if (!executed) {
+          new Notice(this.app, `Unable to execute ${target.label}`);
+        }
+      });
+      return;
+    }
+    if (target.action === "focus") {
+      target.element.focus();
+      return;
+    }
+    target.element.click();
+  }
+}
+
+export function fModePlugin(
+  options: FModePluginOptions = {},
+): AppShellPluginDescriptor {
+  return {
+    id: "fmode",
+    name: "F-Mode",
+    description: "Navigate visible shell actions with keyboard hints.",
+    icon: "scan-search",
+    required: false,
+    enabled: options.enabled ?? true,
+    plugin: FModeAppShellPlugin,
+    options: {
+      hotkeys: options.hotkeys,
+      targetGroups: options.targetGroups ?? [],
+    },
+  };
+}

package/src/shared/workspace/plugins/f-mode/f-mode-session.svelte.ts

@@ -0,0 +1,57 @@
+import {
+  advanceFModeQuery,
+  createFModeEntries,
+  resolveFModeQuery,
+  type FModeEntry,
+} from "./hint-labels.js";
+import type { FModeHintTarget, FModeSettings } from "./types.js";
+
+export class FModeSession {
+  active = $state(false);
+  query = $state("");
+  entries = $state<FModeEntry<FModeHintTarget>[]>([]);
+  settings = $state<FModeSettings | null>(null);
+  invalidSequence = $state(0);
+
+  get visibleEntries(): FModeEntry<FModeHintTarget>[] {
+    return resolveFModeQuery(this.entries, this.query).visible;
+  }
+
+  get exactEntry(): FModeEntry<FModeHintTarget> | undefined {
+    return resolveFModeQuery(this.entries, this.query).exactMatch;
+  }
+
+  open(targets: FModeHintTarget[], settings: FModeSettings): void {
+    this.close();
+    this.settings = settings;
+    this.entries = createFModeEntries(targets, settings.alphabet);
+    this.active = true;
+  }
+
+  close(): void {
+    this.active = false;
+    this.query = "";
+    this.entries = [];
+    this.settings = null;
+  }
+
+  advance(key: string): {
+    accepted: boolean;
+    matchedTarget?: FModeHintTarget;
+  } {
+    const result = advanceFModeQuery(this.entries, this.query, key);
+    if (!result.accepted) {
+      this.invalidSequence += 1;
+      return { accepted: false };
+    }
+    this.query = result.state.query;
+    return {
+      accepted: true,
+      matchedTarget: result.state.exactMatch?.target,
+    };
+  }
+
+  backspace(): void {
+    if (this.query) this.query = this.query.slice(0, -1);
+  }
+}

package/src/shared/workspace/plugins/f-mode/hint-labels.ts

@@ -0,0 +1,123 @@
+export const DEFAULT_FMODE_ALPHABET = "asdfghjklqwertyuiopzxcvbnm";
+
+export interface FModeTargetLike {
+  id: string;
+}
+
+export interface FModeEntry<Target extends FModeTargetLike = FModeTargetLike> {
+  target: Target;
+  hint: string;
+  index: number;
+}
+
+export interface FModeQueryState<
+  Target extends FModeTargetLike = FModeTargetLike,
+> {
+  query: string;
+  visible: FModeEntry<Target>[];
+  exactMatch?: FModeEntry<Target>;
+}
+
+export interface FModeAdvanceResult<
+  Target extends FModeTargetLike = FModeTargetLike,
+> {
+  accepted: boolean;
+  state: FModeQueryState<Target>;
+}
+
+export function normalizeFModeAlphabet(alphabet: string): string[] {
+  return Array.from(
+    new Set(
+      alphabet
+        .toLocaleLowerCase()
+        .split("")
+        .filter((character) => /[a-z0-9]/u.test(character)),
+    ),
+  );
+}
+
+export function createHintLabels(
+  count: number,
+  alphabet = DEFAULT_FMODE_ALPHABET,
+): string[] {
+  if (count <= 0) return [];
+  const characters = normalizeFModeAlphabet(alphabet);
+  if (characters.length === 0) {
+    throw new Error(
+      "F-Mode alphabet must contain at least one alphanumeric key",
+    );
+  }
+  const labels = [...characters];
+  while (labels.length < count) {
+    const shortestLength = Math.min(...labels.map((label) => label.length));
+    let indexToExpand = -1;
+    for (let index = labels.length - 1; index >= 0; index -= 1) {
+      if (labels[index]?.length === shortestLength) {
+        indexToExpand = index;
+        break;
+      }
+    }
+    const prefix = labels[indexToExpand];
+    if (!prefix) throw new Error("Unable to generate enough F-Mode labels");
+    labels.splice(
+      indexToExpand,
+      1,
+      ...characters.map((character) => `${prefix}${character}`),
+    );
+  }
+  return labels.slice(0, count);
+}
+
+export function createFModeEntries<Target extends FModeTargetLike>(
+  targets: Target[],
+  alphabet = DEFAULT_FMODE_ALPHABET,
+): FModeEntry<Target>[] {
+  const labels = createHintLabels(targets.length, alphabet);
+  return targets.map((target, index) => ({
+    target,
+    hint: labels[index]!,
+    index,
+  }));
+}
+
+export function resolveFModeQuery<Target extends FModeTargetLike>(
+  entries: FModeEntry<Target>[],
+  query: string,
+): FModeQueryState<Target> {
+  const normalized = query.toLocaleLowerCase();
+  if (!normalized) return { query: "", visible: entries };
+  const visible = entries.filter((entry) => entry.hint.startsWith(normalized));
+  return {
+    query: normalized,
+    visible,
+    exactMatch: visible.find((entry) => entry.hint === normalized),
+  };
+}
+
+export function normalizeFModeKey(key: string): string | null {
+  return /^[a-z0-9]$/iu.test(key) ? key.toLocaleLowerCase() : null;
+}
+
+export function advanceFModeQuery<Target extends FModeTargetLike>(
+  entries: FModeEntry<Target>[],
+  currentQuery: string,
+  nextKey: string,
+): FModeAdvanceResult<Target> {
+  const normalizedKey = normalizeFModeKey(nextKey);
+  if (!normalizedKey) {
+    return {
+      accepted: false,
+      state: resolveFModeQuery(entries, currentQuery),
+    };
+  }
+  const nextState = resolveFModeQuery(
+    entries,
+    `${currentQuery}${normalizedKey}`,
+  );
+  return nextState.visible.length
+    ? { accepted: true, state: nextState }
+    : {
+        accepted: false,
+        state: resolveFModeQuery(entries, currentQuery),
+      };
+}

package/src/shared/workspace/plugins/f-mode/index.ts

@@ -0,0 +1,6 @@
+export { default as FModeOverlay } from "./FModeOverlay.svelte";
+export { FModeSession } from "./f-mode-session.svelte.js";
+export { fModePlugin } from "./f-mode-plugin.js";
+export * from "./hint-labels.js";
+export * from "./settings.js";
+export type * from "./types.js";