@rimelight/ui 0.0.33 → 0.0.35

package/src/utils/headerStack.ts

@@ -1,95 +1,115 @@
-export interface HeaderLayer {
-  id: string
-  order: number
-  naturalHeight: number
-  isVisible: boolean
-  el: HTMLElement | null
-}
-
-export interface HeaderStackManager {
-  layers: HeaderLayer[]
-  register: (
-    id: string,
-    order: number,
-    naturalHeight: number,
-    isVisible: boolean,
-    el: HTMLElement | null
-  ) => void
-  unregister: (id: string) => void
-  update: () => void
-}
-
-declare global {
-  interface Window {
-    RLHeaderStack?: HeaderStackManager
-  }
-}
-
-/**
- * Initializes and returns a global vanilla JS header stack manager. This ensures Vue and Astro
- * components share the exact same layer state and can dynamically push each other up/down when
- * hiding on scroll.
- */
-export function getHeaderStack(): HeaderStackManager {
-  if (typeof window === "undefined") {
-    // SSR stub
-    return {
-      layers: [],
-      register() {},
-      unregister() {},
-      update() {}
-    }
-  }
-
-  if (!window.RLHeaderStack) {
-    window.RLHeaderStack = {
-      layers: [] as HeaderLayer[],
-      register(
-        id: string,
-        order: number,
-        naturalHeight: number,
-        isVisible: boolean,
-        el: HTMLElement | null
-      ) {
-        let layer = this.layers.find((l: HeaderLayer) => l.id === id)
-        if (!layer) {
-          layer = { id, order, naturalHeight, isVisible, el }
-          this.layers.push(layer)
-          this.layers.sort((a: HeaderLayer, b: HeaderLayer) => a.order - b.order)
-        } else {
-          layer.naturalHeight = naturalHeight
-          layer.isVisible = isVisible
-          layer.el = el
-        }
-        this.update()
-      },
-      unregister(id: string) {
-        this.layers = this.layers.filter((l: HeaderLayer) => l.id !== id)
-        this.update()
-      },
-      update() {
-        let currentTop = 0
-        for (const layer of this.layers) {
-          if (layer.el) {
-            // If hidden, slide it up out of view (or exactly to its negative height so it's ready to slide down)
-            const topPx = layer.isVisible ? `${currentTop}px` : `-${layer.naturalHeight}px`
-            layer.el.style.top = topPx
-            layer.el.style.opacity = layer.isVisible ? "1" : "0"
-            layer.el.style.pointerEvents = layer.isVisible ? "auto" : "none"
-            layer.el.style.setProperty(
-              "--rl-header-bottom",
-              `calc(${topPx} + ${layer.naturalHeight}px)`
-            )
-          }
-          if (layer.isVisible) {
-            currentTop += layer.naturalHeight
-          }
-        }
-        if (currentTop > 0) {
-          document.documentElement.style.setProperty("--rl-total-header-height", `${currentTop}px`)
-        }
-      }
-    }
-  }
-  return window.RLHeaderStack
-}
+export interface HeaderLayer {
+  id: string
+  type: "banner" | "header"
+  order: number
+  naturalHeight: number
+  isVisible: boolean
+  el: HTMLElement | null
+}
+
+export interface HeaderStackManager {
+  layers: HeaderLayer[]
+  register: (
+    id: string,
+    order: number,
+    naturalHeight: number,
+    isVisible: boolean,
+    el: HTMLElement | null,
+    type?: "banner" | "header"
+  ) => void
+  unregister: (id: string) => void
+  update: () => void
+}
+
+declare global {
+  interface Window {
+    RLHeaderStack?: HeaderStackManager
+  }
+}
+
+/**
+ * Initializes and returns a global vanilla JS header stack manager. This ensures Vue and Astro
+ * components share the exact same layer state and can dynamically push each other up/down when
+ * hiding on scroll.
+ */
+export function getHeaderStack(): HeaderStackManager {
+  if (typeof window === "undefined") {
+    // SSR stub
+    return {
+      layers: [],
+      register() {},
+      unregister() {},
+      update() {}
+    }
+  }
+
+  if (!window.RLHeaderStack) {
+    window.RLHeaderStack = {
+      layers: [] as HeaderLayer[],
+      register(
+        id: string,
+        order: number,
+        naturalHeight: number,
+        isVisible: boolean,
+        el: HTMLElement | null,
+        type: "banner" | "header" = "header"
+      ) {
+        if (el && !el.isConnected) return
+        let layer = this.layers.find((l: HeaderLayer) => l.id === id)
+        if (!layer) {
+          layer = { id, type, order, naturalHeight, isVisible, el }
+          this.layers.push(layer)
+          this.layers.sort((a: HeaderLayer, b: HeaderLayer) => {
+            if (a.type !== b.type) return a.type === "banner" ? -1 : 1
+            return a.order - b.order
+          })
+        } else {
+          layer.naturalHeight = naturalHeight
+          layer.isVisible = isVisible
+          layer.el = el
+        }
+        this.update()
+      },
+      unregister(id: string) {
+        const layer = this.layers.find((l: HeaderLayer) => l.id === id)
+        if (layer && layer.el) {
+          const el = layer.el as HTMLElement & {
+            rlScrollListener?: () => void
+            rlResizeObserver?: ResizeObserver
+          }
+          if (el.rlScrollListener) {
+            window.removeEventListener("scroll", el.rlScrollListener)
+          }
+          if (el.rlResizeObserver) {
+            el.rlResizeObserver.disconnect()
+          }
+        }
+        this.layers = this.layers.filter((l: HeaderLayer) => l.id !== id)
+        this.update()
+      },
+      update() {
+        let currentTop = 0
+        for (const layer of this.layers) {
+          if (layer.el) {
+            // If hidden, slide it up out of view (or exactly to its negative height so it's ready to slide down)
+            const topPx = layer.isVisible ? `${currentTop}px` : `-${layer.naturalHeight}px`
+            layer.el.style.top = topPx
+            layer.el.style.opacity = layer.isVisible ? "1" : "0"
+            layer.el.style.pointerEvents = layer.isVisible ? "auto" : "none"
+            layer.el.style.setProperty(
+              "--rl-header-bottom",
+              `calc(${topPx} + ${layer.naturalHeight}px)`
+            )
+          }
+          if (layer.isVisible) {
+            currentTop += layer.naturalHeight
+          }
+        }
+        if (currentTop > 0) {
+          document.documentElement.style.setProperty("--rl-total-header-height", `${currentTop}px`)
+        }
+      }
+    }
+  }
+  return window.RLHeaderStack
+}

package/src/utils/index.ts

@@ -1,5 +1,7 @@
-export * from "./defineTheme"
-export * from "./resolveClasses"
-export * from "./useUi.ts"
-export * from "./docs"
-export * from "./embed"
+export * from "./defineTheme"
+export * from "./resolveClasses"
+export * from "./useUi.ts"
+export * from "./docs"
+export * from "./embed"
+export * from "./shortcuts"
+export * from "./color"

package/src/utils/shortcuts.ts

@@ -0,0 +1,322 @@
+import { atom } from "nanostores"
+
+export type Handler = (e: KeyboardEvent) => void
+
+export interface ShortcutConfig {
+  handler: Handler
+  usingInput?: boolean | string
+  label?: string
+  description?: string
+  category?: string
+  order?: number
+}
+
+export interface ShortcutsConfig {
+  [key: string]: ShortcutConfig | Handler | false | null | undefined
+}
+
+export interface ShortcutsOptions {
+  chainDelay?: number
+}
+
+interface Shortcut {
+  key: string
+  handler: Handler
+  chained: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+  shiftKey: boolean
+  altKey: boolean
+  usingInput?: boolean | string
+}
+
+export interface RegisteredShortcut {
+  id: string
+  keys: string[]
+  label?: string
+  description?: string
+  category?: string
+  order?: number
+}
+
+// OS detection
+const macOS =
+  typeof window !== "undefined" &&
+  typeof navigator !== "undefined" &&
+  /Macintosh;/.test(navigator.userAgent)
+
+// Modifiers map for human-readable display
+const kbdKeysMap: Record<string, string> = {
+  meta: macOS ? "⌘" : "Ctrl",
+  command: macOS ? "⌘" : "Ctrl",
+  ctrl: macOS ? "Ctrl" : "Ctrl",
+  control: macOS ? "Ctrl" : "Ctrl",
+  alt: macOS ? "⌥" : "Alt",
+  option: macOS ? "⌥" : "Alt",
+  shift: macOS ? "⇧" : "Shift",
+  enter: "↵",
+  delete: "⌦",
+  backspace: "⌫",
+  escape: "Esc",
+  tab: "⇥",
+  space: "Space",
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→"
+}
+
+// Convert a combination string (e.g. meta_alt_t) into platform-specific readable key symbol arrays
+export function formatShortcutKeys(keyStr: string): string[] {
+  const separator = keyStr.includes("-") ? "-" : "_"
+  const parts = keyStr.split(separator)
+  return parts.map((part) => {
+    const lower = part.toLowerCase()
+    if (kbdKeysMap[lower] !== undefined) {
+      return kbdKeysMap[lower]
+    }
+    if (lower.length === 1) {
+      return lower.toUpperCase()
+    }
+    return part.charAt(0).toUpperCase() + part.slice(1)
+  })
+}
+
+// Reactive store containing all currently registered shortcuts on the page
+export const activeShortcutsStore = atom<RegisteredShortcut[]>([])
+
+// Simple key to code conversion for layout/translation independence under Alt
+function convertKeyToCode(key: string): string {
+  if (/^[a-z]$/i.test(key)) {
+    return `Key${key.toUpperCase()}`
+  }
+  if (/^\d$/.test(key)) {
+    return `Digit${key}`
+  }
+  if (/^f\d+$/i.test(key)) {
+    return key.toUpperCase()
+  }
+  const specialKeys: Record<string, string> = {
+    space: "Space",
+    enter: "Enter",
+    escape: "Escape",
+    tab: "Tab",
+    backspace: "Backspace",
+    delete: "Delete",
+    arrowup: "ArrowUp",
+    arrowdown: "ArrowDown",
+    arrowleft: "ArrowLeft",
+    arrowright: "ArrowRight"
+  }
+  return specialKeys[key.toLowerCase()] || key
+}
+
+// Input tag checking
+function isUsingInput(activeElement: Element | null): boolean | string {
+  if (!activeElement) return false
+  const tagName = activeElement.tagName
+  const contentEditable = activeElement.getAttribute("contenteditable")
+  const isInput =
+    tagName === "INPUT" ||
+    tagName === "TEXTAREA" ||
+    contentEditable === "true" ||
+    contentEditable === "plaintext-only"
+  if (isInput) {
+    return activeElement.getAttribute("name") || true
+  }
+  return false
+}
+
+export function defineShortcuts(
+  config: ShortcutsConfig,
+  options: ShortcutsOptions = {}
+): () => void {
+  if (typeof window === "undefined") {
+    return () => {}
+  }
+
+  const chainDelay = options.chainDelay ?? 800
+  const chainedInputs: string[] = []
+  let debounceTimer: any = null
+
+  const clearChainedInput = () => {
+    chainedInputs.length = 0
+  }
+
+  // Pre-parse the shortcuts configuration
+  const parsedShortcuts: Shortcut[] = Object.entries(config)
+    .map(([key, shortcutConfig]) => {
+      if (!shortcutConfig) return null
+
+      let handler: Handler
+      let usingInput: boolean | string = false
+
+      if (typeof shortcutConfig === "function") {
+        handler = shortcutConfig
+      } else {
+        handler = shortcutConfig.handler
+        usingInput = shortcutConfig.usingInput ?? false
+      }
+
+      if (!handler) return null
+
+      const chained = key.includes("-") && key !== "-" && !key.includes("_")
+      let baseKey = ""
+      let ctrlKey = false
+      let metaKey = false
+      let shiftKey = false
+      let altKey = false
+
+      if (chained) {
+        baseKey = key.toLowerCase()
+      } else {
+        const parts = key.toLowerCase().split("_")
+        baseKey = parts
+          .filter((p) => !["meta", "command", "ctrl", "shift", "alt", "option"].includes(p))
+          .join("_")
+        ctrlKey = parts.includes("ctrl")
+        metaKey = parts.includes("meta") || parts.includes("command")
+        shiftKey = parts.includes("shift")
+        altKey = parts.includes("alt") || parts.includes("option")
+
+        // Normalize Cmd/Ctrl for non-macOS
+        if (!macOS && metaKey && !ctrlKey) {
+          metaKey = false
+          ctrlKey = true
+        }
+      }
+
+      return {
+        key: baseKey,
+        handler,
+        chained,
+        ctrlKey,
+        metaKey,
+        shiftKey,
+        altKey,
+        usingInput
+      } as Shortcut
+    })
+    .filter((item): item is Shortcut => item != null)
+
+  // Register documented shortcuts to the store
+  const itemsToRegister: RegisteredShortcut[] = Object.entries(config).flatMap(
+    ([key, shortcutConfig]) => {
+      if (!shortcutConfig || typeof shortcutConfig !== "object") return []
+
+      const { label, description, category, order } = shortcutConfig
+      if (!label && !description) return [] // only register documented shortcuts
+
+      const item: RegisteredShortcut = {
+        id: `${key}-${Math.random().toString(36).slice(2, 7)}`,
+        keys: formatShortcutKeys(key),
+        category: category || "system"
+      }
+      if (label) item.label = label
+      if (description) item.description = description
+      if (order !== undefined) item.order = order
+      return [item]
+    }
+  )
+
+  if (itemsToRegister.length > 0) {
+    activeShortcutsStore.set([...activeShortcutsStore.get(), ...itemsToRegister])
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (!e.key) return
+
+    const activeEl = document.activeElement
+    const currentlyUsingInput = isUsingInput(activeEl)
+
+    // Helper to check if a shortcut is enabled given current focus state
+    const isShortcutEnabled = (shortcut: Shortcut) => {
+      if (!shortcut.usingInput) {
+        return !currentlyUsingInput
+      }
+      if (typeof shortcut.usingInput === "string") {
+        return currentlyUsingInput === shortcut.usingInput
+      }
+      return true
+    }
+
+    // Handle chained shortcuts
+    chainedInputs.push(e.key.toLowerCase())
+    clearTimeout(debounceTimer)
+
+    if (chainedInputs.length >= 2) {
+      const chainedKey = chainedInputs.slice(-2).join("-")
+      const matchedChained = parsedShortcuts.find((s) => s.chained && s.key === chainedKey)
+      if (matchedChained && isShortcutEnabled(matchedChained)) {
+        e.preventDefault()
+        matchedChained.handler(e)
+        clearChainedInput()
+        return
+      }
+    }
+
+    // Handle standard shortcuts
+    for (const shortcut of parsedShortcuts) {
+      if (shortcut.chained) continue
+
+      if (e.ctrlKey !== shortcut.ctrlKey) continue
+      if (e.metaKey !== shortcut.metaKey) continue
+      if (e.altKey !== shortcut.altKey) continue
+
+      // Match by code when Alt modifier is active to avoid key translation issues
+      const useCode = shortcut.altKey && e.altKey
+      if (useCode) {
+        if (e.code !== convertKeyToCode(shortcut.key)) continue
+      } else {
+        const pressedKey = e.key.toLowerCase()
+        if (pressedKey !== shortcut.key) continue
+      }
+
+      // Shift modifier check:
+      // If the shortcut explicitly specifies shiftKey: true, then e.shiftKey must be true.
+      // If the shortcut does NOT specify shiftKey: true, but e.shiftKey is true:
+      // - If the base key is a letter (e.g. 'k'), then we do NOT match (because it's Shift+K, not K).
+      // - If the base key is a shiftable control key (like 'arrowleft'), we do NOT match.
+      // - For other keys (like '?', '/', etc.), we allow it to match even if e.shiftKey is true.
+      const alphabetKey = /^[a-z]$/i.test(shortcut.key)
+      const shiftableKeys = [
+        "arrowleft",
+        "arrowright",
+        "arrowup",
+        "arrowdown",
+        "tab",
+        "escape",
+        "enter",
+        "backspace"
+      ]
+      const shiftableKey = shiftableKeys.includes(shortcut.key)
+
+      if (shortcut.shiftKey && !e.shiftKey) continue
+      if (!shortcut.shiftKey && e.shiftKey && (alphabetKey || shiftableKey)) continue
+
+      if (isShortcutEnabled(shortcut)) {
+        e.preventDefault()
+        shortcut.handler(e)
+        clearChainedInput()
+        return
+      }
+    }
+
+    debounceTimer = setTimeout(clearChainedInput, chainDelay)
+  }
+
+  window.addEventListener("keydown", onKeyDown)
+
+  return () => {
+    window.removeEventListener("keydown", onKeyDown)
+    clearTimeout(debounceTimer)
+
+    // Unregister items from the active store
+    if (itemsToRegister.length > 0) {
+      const idsToRemove = new Set(itemsToRegister.map((item) => item.id))
+      activeShortcutsStore.set(
+        activeShortcutsStore.get().filter((item) => !idsToRemove.has(item.id))
+      )
+    }
+  }
+}

package/src/components/TableOfContents.astro

@@ -1,107 +0,0 @@
----
-export interface TableOfContentsHeading {
-  depth: number;
-  slug: string;
-  text: string;
-}
-
-export interface TableOfContentsConfig {
-  minHeadingLevel?: number;
-  maxHeadingLevel?: number;
-}
-
-export interface TableOfContentsProps {
-  headings: TableOfContentsHeading[];
-  /** false = hide entirely, object = heading level bounds */
-  tableOfContents?: false | TableOfContentsConfig;
-  /** @deprecated use tableOfContents.maxHeadingLevel instead */
-  levels?: 1 | 2 | 3;
-}
-
-type Props = TableOfContentsProps;
-
-const { headings, tableOfContents, levels = 2 } = Astro.props as Props;
-
-if (tableOfContents === false) {
-  // Render nothing — parent should also skip rendering this component,
-  // but guard here as a safety net.
-}
-
-const minLevel = (tableOfContents !== false && tableOfContents?.minHeadingLevel) ?? 2;
-const maxLevel = (tableOfContents !== false && tableOfContents?.maxHeadingLevel) ?? levels;
-
-const filteredHeadings = tableOfContents !== false
-  ? headings.filter(h => h.depth >= minLevel && h.depth <= maxLevel)
-  : [];
----
-
-{tableOfContents !== false && filteredHeadings.length > 0 && (
-  <div class="border-border rounded-xs border p-3xs text-sm leading-tight">
-    <h4 class="text-xl font-medium">On this page</h4>
-    <ul class="mt-2xl flex flex-col gap-3xs">
-      {filteredHeadings.map(heading => (
-        <li
-          class:list={{
-            "pl-3xs": heading.depth === 2,
-            "pl-6": heading.depth === 3,
-            "pl-9": heading.depth >= 4
-          }}
-        >
-          <a
-            href={`#${heading.slug}`}
-            class="toc-link transition hover:text-primary-accent"
-          >
-            {heading.text}
-          </a>
-        </li>
-      ))}
-    </ul>
-  </div>
-)}
-
-<style>
-  .toc-current {
-    color: var(--primary);
-    font-weight: 500;
-  }
-</style>
-
-<script>
-  let wrappingElement: Element | null;
-  let observeHeaderTags: IntersectionObserver;
-  let allHeaderTags: NodeListOf<Element>;
-
-  function setCurrent(e: IntersectionObserverEntry[]) {
-    const allSectionLinks = document.querySelectorAll(".toc-link");
-    e.map(i => {
-      if (i.isIntersecting === true) {
-        allSectionLinks.forEach(link => link.classList.remove("toc-current"));
-        const targetLink = document.querySelector(`a[href="#${i.target.id}"].toc-link`);
-        if (targetLink) targetLink.classList.add("toc-current");
-      }
-    });
-  }
-
-  function initTOC() {
-    wrappingElement = document.querySelector(".markdown-content");
-    if (wrappingElement !== null) {
-      allHeaderTags = wrappingElement.querySelectorAll(":scope > h1, :scope > h2, :scope > h3, :scope > h4");
-    }
-
-    const options: IntersectionObserverInit = {
-      root: null,
-      rootMargin: "0px 0px -50% 0px",
-      threshold: [1]
-    };
-
-    observeHeaderTags = new IntersectionObserver(setCurrent, options);
-    if (wrappingElement === null) return;
-    allHeaderTags.forEach(tag => {
-      tag.classList.add("scroll-mt-3xl");
-      observeHeaderTags.observe(tag);
-    });
-  }
-
-  initTOC();
-  document.addEventListener("astro:after-swap", initTOC);
-</script>