@kahitsan/ksui 0.10.1 → 0.11.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;
+}

package/host-ui.d.ts

@@ -1,145 +0,0 @@
-// CANONICAL SDK type defs for the host UI kit (window.__KSERP_UI__, externalized
-// as "@kserp/host-ui"). This ships in @kahitsan/ksui and is the single
-// source of truth. Every plugin (ours, and any third-party with no kernel
-// source) gets it from the installed package via
-// `/// <reference types="@kahitsan/ksui/host-ui" />`; there are no more
-// per-plugin copies to drift. The host owns the runtime: its remote loader
-// (kserp src/lib/remote-loader.ts) populates the global from the host's kit
-// barrel (kserp src/lib/host-ui.tsx) before loading any remote. Keep this in sync
-// with that barrel. Every member here must be exported there, and vice versa.
-declare module "@kserp/host-ui" {
-  import type { JSX, Accessor } from "solid-js";
-
-  // --- Shared table types (mirror src/components/ui/DataTable/DataTable.tsx) ---
-  export interface DataTableRow {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: any;
-  }
-  export interface DataTableColumn<T extends DataTableRow> {
-    data: (keyof T & string) | null;
-    title?: string;
-    render?: (
-      data: T[keyof T] | null,
-      type: "display",
-      row: T,
-      meta: { row: number; col: number; search: string },
-    ) => JSX.Element | string;
-    orderable?: boolean;
-    className?: string;
-  }
-  export interface FetchResult<T> {
-    data: T[];
-    total: number;
-  }
-  export interface FetchParams {
-    page: number;
-    limit: number;
-    search: string;
-    sortBy: string | null;
-    sortDir: "asc" | "desc";
-    dateFilter: string | null;
-    dateFrom?: string | null;
-    dateTo?: string | null;
-  }
-
-  export interface DataTableProps<T extends DataTableRow> {
-    columns?: DataTableColumn<T>[];
-    /**
-     * Generic data fetcher. When provided, the table runs in server-side mode.
-     * Optional: omit it and pass `data` for client-side mode.
-     */
-    fetchFn?: (params: FetchParams) => Promise<FetchResult<T>>;
-    /** Static data (client-side mode). Ignored when `fetchFn` is set. */
-    data?: T[];
-    /**
-     * Expose the table's refetch handle to the parent. The callback receives
-     * `{ refetch, resetAndRefetch }`: `refetch()` re-fetches with the current
-     * state; `resetAndRefetch()` resets pagination to page 1 (clearing loadMore
-     * accumulators) before fetching.
-     */
-    onRefetch?: (api: { refetch: () => void; resetAndRefetch: () => void }) => void;
-    // Remaining props are passed through; kept permissive so plugins can use the
-    // full surface of the host component without re-declaring it here.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: any;
-  }
-  export function DataTable<T extends DataTableRow>(props: DataTableProps<T>): JSX.Element;
-
-  // --- DatePicker ---
-  export interface DateRangeValue {
-    start: string | null;
-    end: string | null;
-  }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export function DatePicker(props: any): JSX.Element;
-
-  // --- Modal ---
-  // The Modal is mounted/unmounted by the caller (wrap it in <Show when={open}>);
-  // there is no `open` prop. onClose fires on Escape / backdrop / dismissal.
-  export type ModalSize = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "5xl" | "7xl";
-  export type ModalTone = "default" | "danger";
-  export interface ModalProps {
-    onClose: () => void;
-    dismissable?: boolean;
-    variant?: "default" | "sheet";
-    size?: ModalSize;
-    tone?: ModalTone;
-    ariaLabel?: string;
-    children: JSX.Element;
-  }
-  export function Modal(props: ModalProps): JSX.Element;
-
-  // --- SearchableSelect ---
-  export interface SearchableOption {
-    value: string;
-    label: string;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [key: string]: any;
-  }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export function SearchableSelect(props: any): JSX.Element;
-
-  // --- Other components (permissive: full prop surface lives in the host) ---
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const Button: (props: any) => JSX.Element;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const PageShell: (props: any) => JSX.Element;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const PageTitle: (props: any) => JSX.Element;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const PageShareButton: (props: any) => JSX.Element;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const Avatar: (props: any) => JSX.Element;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export const PluginPageLoader: (props: any) => JSX.Element;
-
-  // --- Confirm ---
-  export function confirm(opts: {
-    title?: string;
-    message?: string;
-    confirmLabel?: string;
-    cancelLabel?: string;
-    danger?: boolean;
-  }): Promise<boolean>;
-
-  // --- Host hooks (run on the host's Solid runtime + context providers) ---
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export function useActiveWorkspace(): any;
-  export function useCan(code: string): Accessor<boolean>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export function usePermissions(): any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  export function PermissionGate(props: any): JSX.Element;
-
-  // --- Helpers ---
-  export function highlightMatch(text: string, query: string, markClass?: string): JSX.Element;
-  export function HighlightedText(props: {
-    text: string;
-    query: string;
-    markClass?: string;
-  }): JSX.Element;
-  export function matchesQuery(text: string | null | undefined, query: string): boolean;
-  export function matchesAny(query: string, ...fields: (string | null | undefined)[]): boolean;
-  export function useFocusTrap(el: HTMLElement | undefined): () => void;
-  export function autoFocusOnMount(el: HTMLElement | undefined): void;
-}