@kahitsan/ksui 0.10.2 → 0.12.0

package/src/utils/dom.ts

@@ -0,0 +1,197 @@
+// Selector for elements a Tab key would normally land on. Picker dropdowns
+// in this app render their popups via Portal outside the modal's subtree,
+// so the trap also has to consider those, but options/inputs inside a
+// Portal are still owned by the open modal logically. The trap solves this
+// by also walking matching descendants of the document body that point back
+// to the modal via aria-controls / aria-labelledby. For phase 1, the
+// simpler implementation is sufficient: every modal in this app keeps its
+// own focusable descendants inside the dialog node itself, and pickers
+// close on Escape independently of the trap.
+const TABBABLE_SELECTOR = [
+  'a[href]:not([tabindex="-1"])',
+  'button:not([disabled]):not([tabindex="-1"])',
+  'input:not([type="hidden"]):not([disabled]):not([tabindex="-1"])',
+  'select:not([disabled]):not([tabindex="-1"])',
+  'textarea:not([disabled]):not([tabindex="-1"])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(", ");
+
+function tabbablesIn(root: HTMLElement): HTMLElement[] {
+  // Walk the modal's subtree and keep visible, non-disabled focusables.
+  return Array.from(root.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)).filter((el) => {
+    if (el.hidden) return false;
+    // offsetParent is null for `display: none` and detached nodes; visibility
+    // hidden elements are excluded too. Don't trust just the selector list.
+    if (el.offsetParent === null && getComputedStyle(el).position !== "fixed") return false;
+    return true;
+  });
+}
+
+/**
+ * While any modal is open, suppress the browser/PWA pull-to-refresh and
+ * overscroll-bounce gestures so a stray drag on the backdrop doesn't reload
+ * the page out from under a half-filled form. Counter handles nested modals
+ * (e.g. a Confirm dialog opening on top of a transactions sheet).
+ *
+ * Pair `lockPullToRefresh()` with `unlockPullToRefresh()` (e.g. via Solid
+ * `onCleanup`) so each lock has exactly one matching unlock.
+ */
+let openModalCount = 0;
+let prevHtmlOverscroll: string | null = null;
+let prevBodyOverscroll: string | null = null;
+
+export function lockPullToRefresh() {
+  if (typeof document === "undefined") return;
+  if (openModalCount === 0) {
+    const html = document.documentElement;
+    const body = document.body;
+    prevHtmlOverscroll = html.style.overscrollBehavior;
+    prevBodyOverscroll = body.style.overscrollBehavior;
+    html.style.overscrollBehavior = "none";
+    body.style.overscrollBehavior = "none";
+  }
+  openModalCount += 1;
+}
+
+export function unlockPullToRefresh() {
+  if (typeof document === "undefined") return;
+  openModalCount = Math.max(0, openModalCount - 1);
+  if (openModalCount === 0) {
+    document.documentElement.style.overscrollBehavior = prevHtmlOverscroll ?? "";
+    document.body.style.overscrollBehavior = prevBodyOverscroll ?? "";
+    prevHtmlOverscroll = null;
+    prevBodyOverscroll = null;
+  }
+}
+
+/**
+ * Trap Tab and Shift+Tab inside `el` and restore focus on cleanup. Returns
+ * a teardown function the caller can use to deactivate the trap explicitly
+ * (also runs automatically when called inside a Solid `onCleanup`).
+ *
+ * Use this from a ref callback or Solid effect:
+ *
+ *   <div ref={(el) => { onCleanup(useFocusTrap(el)); }}>
+ *
+ * Or from an effect:
+ *
+ *   createEffect(() => {
+ *     if (containerRef) onCleanup(useFocusTrap(containerRef));
+ *   });
+ *
+ * The trap only intercepts Tab. Escape, click-outside, and submit handling
+ * remain the modal's responsibility, the trap is purely a focus-keeper.
+ */
+export function useFocusTrap(el: HTMLElement | undefined): () => void {
+  if (!el) return () => {};
+
+  // Snapshot the element that had focus before the modal mounted so we can
+  // hand it back when the trap deactivates. Skip the document body which is
+  // a non-actionable default.
+  const previouslyFocused =
+    document.activeElement instanceof HTMLElement && document.activeElement !== document.body
+      ? document.activeElement
+      : null;
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key !== "Tab") return;
+    const list = tabbablesIn(el);
+    if (list.length === 0) {
+      // No focusable descendants (an empty modal), pin focus on the
+      // container itself rather than letting the browser tab away.
+      e.preventDefault();
+      el.focus();
+      return;
+    }
+    const first = list[0];
+    const last = list[list.length - 1];
+    const active = document.activeElement as HTMLElement | null;
+    const inTrap = active && el.contains(active);
+    if (e.shiftKey) {
+      if (!inTrap || active === first) {
+        e.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (!inTrap || active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  };
+
+  // Capture phase so we see the keydown before any descendant handler can
+  // swallow it. Solid's <Show>/<Portal> wrapping doesn't change that.
+  document.addEventListener("keydown", handleKeyDown, true);
+
+  return () => {
+    document.removeEventListener("keydown", handleKeyDown, true);
+    // Restore focus only when the snapshot is still in the DOM. If the
+    // caller removed the original button between mount and unmount,
+    // dropping focus on a detached element would just clear it instead.
+    if (previouslyFocused && document.contains(previouslyFocused)) {
+      try {
+        previouslyFocused.focus();
+      } catch {
+        /* element became unfocusable in the meantime, let the browser pick */
+      }
+    }
+  };
+}
+
+/**
+ * Ref callback that moves focus into a freshly mounted container so keyboard
+ * users land somewhere meaningful. Used on modal content containers:
+ * `ref={autoFocusOnMount}`.
+ *
+ * Lookup order:
+ *   1. An explicit `[data-autofocus]` element (or its first focusable
+ *      descendant). Lets a parent override the default heuristic when the
+ *      first visible input is not the right place to land, e.g. a modal
+ *      whose primary affordance is a search/picker rather than a date field.
+ *   2. The first text-entry control (input/textarea/select). Most modals open
+ *      onto a form, and dropping focus directly into the first field is what
+ *      sighted keyboard users expect.
+ *   3. Any other focusable element (button, link, anything with `tabindex`).
+ *      A modal that opens onto an action grid (e.g. the Counter cart) has no
+ *      inputs on first render; without this fallback `el.focus()` would never
+ *      run and focus would stay on the button that opened the modal.
+ */
+export function autoFocusOnMount(el: HTMLElement | undefined) {
+  if (!el) return;
+  queueMicrotask(() => {
+    const focusableSelector =
+      'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])';
+    const inputSelector =
+      'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), select:not([disabled])';
+
+    const marker = el.querySelector<HTMLElement>("[data-autofocus]");
+    if (marker) {
+      // The marker itself may be focusable; prefer it. Otherwise pick the
+      // first focusable descendant (e.g. the trigger button inside a custom
+      // picker component).
+      if (marker.matches(focusableSelector)) {
+        marker.focus();
+        return;
+      }
+      const inner = marker.querySelector<HTMLElement>(focusableSelector);
+      if (inner) {
+        inner.focus();
+        return;
+      }
+    }
+
+    const input = el.querySelector<HTMLElement>(inputSelector);
+    if (input) {
+      input.focus();
+      return;
+    }
+    // Fall back to the first interactive element. tabindex="-1" is excluded
+    // so a programmatically-focusable container does not steal focus from a
+    // child the user can actually act on.
+    const focusable = el.querySelector<HTMLElement>(
+      'button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])',
+    );
+    focusable?.focus();
+  });
+}

package/src/utils/highlight.tsx

@@ -0,0 +1,67 @@
+// Search-match highlighting + tiny string-match helpers. Ported into ksui from
+// the former host kit so the library is self-contained: ComboBox and
+// MarkdownNotes used to import `highlightMatch` from "@kserp/host-ui"; they now
+// import it from here. Pure functions plus a `<mark>` wrapper.
+//
+// The default highlight tint ships as injected CSS (a `.ksui-mark` class) so the
+// library carries no Tailwind dependency — like Button/ProgressBar, the keyframe
+// /helper class is added once per page via a runtime <style> tag. Callers can
+// still pass their own `markClass` to override.
+
+import { type JSX } from "solid-js";
+
+const MARK_STYLE_ID = "ksui-mark-style";
+
+function ensureMarkStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(MARK_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = MARK_STYLE_ID;
+  style.textContent = `.ksui-mark{background-color:rgba(245,158,11,0.3);color:inherit;border-radius:2px;}`;
+  document.head.appendChild(style);
+}
+
+/** Case-insensitive substring test. Empty query matches everything. */
+export function matchesQuery(text: string | null | undefined, query: string): boolean {
+  if (!query) return true;
+  if (!text) return false;
+  return text.toLowerCase().includes(query.toLowerCase());
+}
+
+/** True when the query matches any of the given fields. */
+export function matchesAny(query: string, ...fields: (string | null | undefined)[]): boolean {
+  if (!query) return true;
+  return fields.some((f) => matchesQuery(f, query));
+}
+
+/**
+ * Wrap every case-insensitive occurrence of `query` inside `text` in a `<mark>`.
+ * Pass `markClass` to override the default `.ksui-mark` tint.
+ */
+export function highlightMatch(text: string, query: string, markClass?: string): JSX.Element {
+  if (!query || !text) return <>{text}</>;
+  if (!markClass) ensureMarkStyle();
+  const lower = text.toLowerCase();
+  const q = query.toLowerCase();
+  const out: JSX.Element[] = [];
+  let i = 0;
+  let idx = lower.indexOf(q, i);
+  let key = 0;
+  while (idx !== -1) {
+    if (idx > i) out.push(<>{text.slice(i, idx)}</>);
+    out.push(
+      <mark class={markClass ?? "ksui-mark"} data-key={key++}>
+        {text.slice(idx, idx + q.length)}
+      </mark>,
+    );
+    i = idx + q.length;
+    idx = lower.indexOf(q, i);
+  }
+  if (i < text.length) out.push(<>{text.slice(i)}</>);
+  return <>{out}</>;
+}
+
+/** Component form of {@link highlightMatch}. */
+export function HighlightedText(props: { text: string; query: string; markClass?: string }): JSX.Element {
+  return <>{highlightMatch(props.text, props.query, props.markClass)}</>;
+}

package/src/utils/integration.ts

@@ -0,0 +1,49 @@
+// Optional host integrations.
+//
+// A couple of ksui components can do MORE when the surrounding app feeds them
+// runtime context — a permission check (MarkdownNotes gates its client-mention
+// hover card on "clients.view") and the active workspace id (useAccountsIndex
+// re-keys its fetch per workspace). The library used to pull these from
+// "@kserp/host-ui"; it now owns a tiny opt-in registry instead, so it stays a
+// standalone dependency-free package.
+//
+// Default behavior with nothing configured (any plain SolidJS consumer):
+//   - canAccess(code) === false   → MarkdownNotes renders a plain, non-hovering
+//                                    mention chip.
+//   - getActiveWorkspaceId() === null → useAccountsIndex stays empty (its fetch
+//                                    short-circuits), so accounts resolve to the
+//                                    type-default glyph.
+//
+// A host app wires the real behavior once at startup:
+//   import { configurePermissions, configureActiveWorkspace } from "@kahitsan/ksui";
+//   configurePermissions((code) => usePermissions().has(code));
+//   configureActiveWorkspace(() => useActiveWorkspace().activeWorkspace()?.ws_id ?? null);
+//
+// The resolvers may read reactive sources; ksui calls them inside tracking
+// scopes, so a signal-backed permission/workspace value stays reactive.
+
+type PermissionResolver = (code: string) => boolean;
+type WorkspaceResolver = () => number | string | null;
+
+let permissionResolver: PermissionResolver | null = null;
+let workspaceResolver: WorkspaceResolver | null = null;
+
+/** Register the host's permission check. Pass a function so it can read a reactive source. */
+export function configurePermissions(resolver: PermissionResolver): void {
+  permissionResolver = resolver;
+}
+
+/** True when the host granted `code`. False when no resolver is configured. */
+export function canAccess(code: string): boolean {
+  return permissionResolver ? !!permissionResolver(code) : false;
+}
+
+/** Register the host's active-workspace id getter. Pass a function so it can read a reactive source. */
+export function configureActiveWorkspace(resolver: WorkspaceResolver): void {
+  workspaceResolver = resolver;
+}
+
+/** The host's active workspace id, or null when no resolver is configured. */
+export function getActiveWorkspaceId(): number | string | null {
+  return workspaceResolver ? workspaceResolver() : null;
+}