vanilla-jui 1.7.6 → 1.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-jui",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "private": false,
   "description": "A lightweight, reactive, and fully customizable vanilla JS UI library.",
   "keywords": [

package/src/components/toc.ts

@@ -1,35 +1,44 @@
 import {
   For,
+  Show,
   createDeepStore,
+  createEffect,
   createMemo,
   flushSync,
+  insert,
   jsx,
+  untrack,
 } from 'vanilla-signal';
 
 import {
   type FunctionalComponent,
   defineComponent,
 } from '../core/component.ts';
-import {
-  type DOMReference,
-  all,
-  joinClasses,
-  requireContainer,
-} from '../utilities/dom.ts';
+import { type DOMReference, all, requireContainer } from '../utilities/dom.ts';
 import { createEventManager } from '../utilities/events.ts';
-import { randomId } from '../utilities/id.ts';
 import { type ConfigSchema, resolveConfig } from '../utilities/config.ts';
+import { translate } from '../utilities/locale.ts';
 
 interface TocClassNames {
   toc: string;
+  title: string;
   list: string;
   link: string;
-  active: string;
-  levelPrefix: string;
+  indicator: string;
 }
 
 type TocClassNameConfig = Partial<TocClassNames>;
 
+interface TocIndicatorConfig {
+  width: string;
+  heightRatio: number;
+  radius: string;
+  left: string;
+  color: string;
+}
+
+type TocIndicatorConfigInput = Partial<TocIndicatorConfig>;
+
 export interface TocItem {
   id: string;
   text: string;
@@ -41,11 +50,21 @@ export interface TocCurrent {
   item: TocItem | null;
 }
 
+export interface TocIndicator {
+  visible: boolean;
+  top: number;
+  height: number;
+  duration: number;
+  timingFunction: string;
+}
+
 interface TocProps extends Record<string, unknown> {
   target?: DOMReference;
   headings?: string;
   offset?: number;
   reactive?: boolean;
+  title?: boolean;
+  indicator?: TocIndicatorConfigInput;
   className?: TocClassNameConfig;
   onChange?:
     | ((item: TocItem | null, index: number, toc: TocInstance) => void)
@@ -57,6 +76,8 @@ interface ResolvedTocProps extends Record<string, unknown> {
   headings: string;
   offset: number;
   reactive: boolean;
+  title: boolean;
+  indicator: TocIndicatorConfig;
   className: TocClassNames;
   onChange:
     | ((item: TocItem | null, index: number, toc: TocInstance) => void)
@@ -66,6 +87,7 @@ interface ResolvedTocProps extends Record<string, unknown> {
 interface TocState extends Record<string, unknown> {
   items: TocItem[];
   current: TocCurrent;
+  indicator: TocIndicator;
 }
 
 interface TocRuntimeExtras {
@@ -73,6 +95,8 @@ interface TocRuntimeExtras {
   frameId: number;
   refreshing: boolean;
   refreshFrameId: number;
+  layoutFrameId: number;
+  pendingScroll: TocPendingScroll | null;
 }
 
 interface TocScrollOptions {
@@ -80,6 +104,12 @@ interface TocScrollOptions {
   updateHash?: boolean;
 }
 
+interface TocPendingScroll {
+  index: number;
+  top: number;
+  deadline: number;
+}
+
 interface TocActions {
   activate(index: number): TocInstance;
 }
@@ -93,10 +123,18 @@ type TocInstance = FunctionalComponent<
 
 const DEFAULT_CLASS_NAMES: TocClassNames = {
   toc: 'j-toc',
+  title: 'toc-title',
   list: 'toc-list',
   link: 'toc-link',
-  active: 'is-active',
-  levelPrefix: 'is-level-',
+  indicator: 'toc-indicator',
+};
+
+const DEFAULT_INDICATOR_CONFIG: TocIndicatorConfig = {
+  width: '2px',
+  heightRatio: 5,
+  radius: '2px',
+  left: '0',
+  color: 'var(--tone-solid)',
 };
 
 const TOC_PROPS_SCHEMA = {
@@ -108,6 +146,24 @@ const TOC_PROPS_SCHEMA = {
     min: 0,
   },
   reactive: { default: false, type: 'boolean' },
+  title: { default: false, type: 'boolean' },
+  indicator: {
+    default: DEFAULT_INDICATOR_CONFIG,
+    type: 'plainObject',
+    merge: 'shallow',
+    schema: {
+      width: { default: DEFAULT_INDICATOR_CONFIG.width, type: 'string' },
+      heightRatio: {
+        default: DEFAULT_INDICATOR_CONFIG.heightRatio,
+        type: 'number',
+        min: 1,
+        max: 10,
+      },
+      radius: { default: DEFAULT_INDICATOR_CONFIG.radius, type: 'string' },
+      left: { default: DEFAULT_INDICATOR_CONFIG.left, type: 'string' },
+      color: { default: DEFAULT_INDICATOR_CONFIG.color, type: 'string' },
+    },
+  },
   className: {
     default: DEFAULT_CLASS_NAMES,
     type: 'plainObject',
@@ -117,6 +173,11 @@ const TOC_PROPS_SCHEMA = {
 } satisfies ConfigSchema<TocProps>;
 
 const ACTIVE_OFFSET_TOLERANCE = 1;
+const INDICATOR_TRANSITION_MAX_MS = 1200;
+const INDICATOR_TRANSITION_MIN_MS = 120;
+const INDICATOR_TRANSITION_TIMING = 'ease-in-out';
+const PROGRAMMATIC_SCROLL_TIMEOUT_MS = 2400;
+const SCROLL_REACHED_TOLERANCE = 2;
 
 function normalizeProps(input: TocProps): ResolvedTocProps {
   const props = resolveConfig(input, TOC_PROPS_SCHEMA, 'Toc.props');
@@ -125,6 +186,8 @@ function normalizeProps(input: TocProps): ResolvedTocProps {
     headings: props.headings as string,
     offset: props.offset as number,
     reactive: props.reactive as boolean,
+    title: props.title as boolean,
+    indicator: props.indicator as TocIndicatorConfig,
     className: props.className as TocClassNames,
     onChange: props.onChange as ResolvedTocProps['onChange'],
   };
@@ -135,45 +198,260 @@ function resolveHeadingLevel(element: Element): number {
   return match ? Number(match[1]) : 1;
 }
 
-function normalizeHeading(element: HTMLHeadingElement, index: number): TocItem {
-  if (!element.id) element.id = `toc-${randomId()}-${index}`;
+function normalizeHeadingId(
+  element: HTMLHeadingElement,
+  index: number,
+  usedIds: Set<string>
+): string {
+  const textId = (element.textContent || '').trim().replace(/\s+/g, '-');
+  const base = element.id || textId || `heading-${index + 1}`;
+  let id = base;
+  let suffix = 1;
+  while (usedIds.has(id)) {
+    id = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  element.id = id;
+  usedIds.add(id);
+  return id;
+}
+
+function normalizeHeading(
+  element: HTMLHeadingElement,
+  index: number,
+  usedIds: Set<string>
+): TocItem {
   return {
-    id: element.id,
+    id: normalizeHeadingId(element, index, usedIds),
     text: element.textContent || '',
     level: resolveHeadingLevel(element),
   };
 }
 
+function normalizeHeadings(elements: HTMLHeadingElement[]): TocItem[] {
+  const usedIds = new Set<string>();
+  return elements.map((element, index) =>
+    normalizeHeading(element, index, usedIds)
+  );
+}
+
 export function createToc(props: TocProps = {}): TocInstance {
   const settings = normalizeProps(props);
   const state = createDeepStore({
     items: [],
     current: { index: -1, item: null },
+    indicator: {
+      visible: false,
+      top: 0,
+      height: 0,
+      duration: 0,
+      timingFunction: INDICATOR_TRANSITION_TIMING,
+    },
   }) as TocState;
   const runtime: TocRuntimeExtras = {
     ticking: false,
     frameId: 0,
     refreshing: false,
     refreshFrameId: 0,
+    layoutFrameId: 0,
+    pendingScroll: null,
   };
   const events = createEventManager();
   let target: Element | null = null;
   let headings: HTMLHeadingElement[] = [];
   let observer: MutationObserver | null = null;
+  let listElement: HTMLElement | null = null;
   let toc: TocInstance;
-  const renderableItems = createMemo(() => state.items);
+  let activeLinkId: string | null = null;
+  let listHeight = 0;
+  const linkRefs = new Map<string, HTMLElement>();
+  const getItems = (): TocItem[] =>
+    Array.isArray(state.items) ? state.items : [];
+  const hasItems = (): boolean => getItems().length > 0;
+  const renderableItems = createMemo(getItems);
+
+  const setIndicator = (indicator: TocIndicator): void => {
+    if (
+      state.indicator.visible === indicator.visible &&
+      state.indicator.top === indicator.top &&
+      state.indicator.height === indicator.height &&
+      state.indicator.duration === indicator.duration &&
+      state.indicator.timingFunction === indicator.timingFunction
+    ) {
+      return;
+    }
+    flushSync(() => {
+      state.indicator = indicator;
+    });
+  };
+
+  const hiddenIndicator = (): TocIndicator => ({
+    visible: false,
+    top: 0,
+    height: 0,
+    duration: 0,
+    timingFunction: INDICATOR_TRANSITION_TIMING,
+  });
+
+  const pruneLinkRefs = (items: TocItem[]): void => {
+    const ids = new Set(items.map((item) => item.id));
+    for (const id of linkRefs.keys()) {
+      if (!ids.has(id)) linkRefs.delete(id);
+    }
+  };
+
+  const setLinkCurrent = (id: string, active: boolean): void => {
+    const link = linkRefs.get(id);
+    if (!link) return;
+    if (active) {
+      if (link.getAttribute('aria-current') !== 'location') {
+        link.setAttribute('aria-current', 'location');
+      }
+      return;
+    }
+    if (link.hasAttribute('aria-current')) link.removeAttribute('aria-current');
+  };
+
+  const syncActiveMarker = (nextId: string | null): void => {
+    if (activeLinkId === nextId) return;
+    const previousId = activeLinkId;
+    activeLinkId = nextId;
+    if (previousId) setLinkCurrent(previousId, false);
+    if (nextId) setLinkCurrent(nextId, true);
+  };
+
+  const updateIndicatorForItem = (item: TocItem | null): number => {
+    if (!toc.runtime.built || !listElement || !item) {
+      setIndicator(hiddenIndicator());
+      return 0;
+    }
+    const link = linkRefs.get(item.id);
+    if (!link) {
+      setIndicator(hiddenIndicator());
+      return -1;
+    }
+    if (listHeight <= 0) {
+      const listRect = listElement.getBoundingClientRect();
+      listHeight = listElement.offsetHeight || listRect.height;
+    }
+    const linkRect = link.getBoundingClientRect();
+    const linkHeight = link.offsetHeight || linkRect.height;
+    const linkTop = link.offsetTop;
+    const height = (linkHeight * settings.indicator.heightRatio) / 10;
+    const top = linkTop + (linkHeight - height) / 2;
+    const distance = state.indicator.visible
+      ? Math.abs(top - state.indicator.top)
+      : 0;
+    const duration =
+      distance > 0 && listHeight > 0
+        ? Math.min(
+            INDICATOR_TRANSITION_MAX_MS,
+            Math.max(
+              INDICATOR_TRANSITION_MIN_MS,
+              Math.round((distance / listHeight) * INDICATOR_TRANSITION_MAX_MS)
+            )
+          )
+        : 0;
+    setIndicator({
+      visible: height > 0,
+      top,
+      height,
+      duration,
+      timingFunction: INDICATOR_TRANSITION_TIMING,
+    });
+    return duration;
+  };
+
+  const syncListLayout = (): void => {
+    const items = getItems();
+    if (!toc.runtime.built || !listElement || items.length === 0) {
+      listHeight = 0;
+      setIndicator(hiddenIndicator());
+      return;
+    }
+    pruneLinkRefs(items);
+    const listRect = listElement.getBoundingClientRect();
+    listHeight = listElement.offsetHeight || listRect.height;
+    const current = items[state.current.index] || null;
+    updateIndicatorForItem(current);
+  };
+
+  const scheduleListLayoutSync = (): void => {
+    if (runtime.layoutFrameId) return;
+    runtime.layoutFrameId = requestAnimationFrame(() => {
+      runtime.layoutFrameId = 0;
+      untrack(syncListLayout);
+    });
+  };
+
+  const bindLinkRef = (item: TocItem, element: HTMLElement): void => {
+    linkRefs.set(item.id, element);
+    if (item.id === activeLinkId) {
+      element.setAttribute('aria-current', 'location');
+    } else {
+      element.removeAttribute('aria-current');
+    }
+    scheduleListLayoutSync();
+  };
+
+  const getScrollY = (): number => window.scrollY || window.pageYOffset || 0;
+
+  const getClockTime = (): number => window.performance?.now?.() ?? Date.now();
+
+  const clearPendingScroll = (): void => {
+    runtime.pendingScroll = null;
+  };
+
+  const beginPendingScroll = (
+    index: number,
+    top: number,
+    duration: number
+  ): void => {
+    if (!Number.isInteger(index) || index < 0) return;
+    runtime.pendingScroll = {
+      index,
+      top,
+      deadline:
+        getClockTime() + Math.max(PROGRAMMATIC_SCROLL_TIMEOUT_MS, duration),
+    };
+  };
 
-  const setActive = (index: number): void => {
-    if (index === state.current.index) return;
-    const current = state.items[index] || null;
+  const shouldSkipScrollActivation = (): boolean => {
+    const pending = runtime.pendingScroll;
+    if (!pending) return false;
+    if (Math.abs(getScrollY() - pending.top) <= SCROLL_REACHED_TOLERANCE) {
+      clearPendingScroll();
+      return true;
+    }
+    if (getClockTime() > pending.deadline) {
+      clearPendingScroll();
+      return false;
+    }
+    return true;
+  };
+
+  const setActive = (index: number): number => {
+    const items = getItems();
+    if (index === state.current.index) {
+      const current = items[index] || null;
+      const duration = updateIndicatorForItem(current);
+      if (duration < 0) scheduleListLayoutSync();
+      return duration;
+    }
+    const current = items[index] || null;
     flushSync(() => {
       state.current = { index, item: current };
     });
+    syncActiveMarker(current?.id ?? null);
+    const duration = updateIndicatorForItem(current);
+    if (duration < 0) scheduleListLayoutSync();
     settings.onChange?.(current, index, toc);
+    return duration;
   };
 
   const updateActive = (): void => {
     if (!toc.runtime.built) return;
+    if (shouldSkipScrollActivation()) return;
     let index = -1;
     const activeOffset = settings.offset + ACTIVE_OFFSET_TOLERANCE;
     for (let current = headings.length - 1; current >= 0; current--) {
@@ -211,13 +489,16 @@ export function createToc(props: TocProps = {}): TocInstance {
   ): void => {
     const heading = headings.find((element) => element.id === item.id);
     if (!heading) return;
-    const scrollY = window.scrollY || window.pageYOffset || 0;
+    const scrollY = getScrollY();
     const top = Math.max(
       0,
       heading.getBoundingClientRect().top + scrollY - settings.offset
     );
+    if (activeIndex >= 0) {
+      const duration = setActive(activeIndex);
+      beginPendingScroll(activeIndex, top, duration);
+    }
     window.scrollTo({ top, behavior: 'smooth' });
-    if (activeIndex >= 0) setActive(activeIndex);
     if (updateHash && window.history?.pushState) {
       window.history.pushState(null, '', `#${item.id}`);
     }
@@ -226,22 +507,26 @@ export function createToc(props: TocProps = {}): TocInstance {
   const syncFromTarget = (): void => {
     if (toc.runtime.destroyed || !toc.runtime.built || !target) return;
     headings = all<HTMLHeadingElement>(settings.headings, target);
-    const items = headings.map(normalizeHeading);
+    clearPendingScroll();
+    const items = normalizeHeadings(headings);
+    syncActiveMarker(null);
     flushSync(() => {
       state.items = items;
       state.current = { index: -1, item: null };
+      state.indicator = hiddenIndicator();
     });
     updateActive();
   };
 
   const activate = (index: number): TocInstance => {
+    const items = getItems();
     if (
       toc.runtime.built &&
       Number.isInteger(index) &&
       index >= 0 &&
-      index < state.items.length
+      index < items.length
     ) {
-      scrollToItem(state.items[index]);
+      scrollToItem(items[index], { activeIndex: index });
     }
     return toc;
   };
@@ -251,48 +536,98 @@ export function createToc(props: TocProps = {}): TocInstance {
     props: settings,
     state,
     actions: { activate },
-    view: () =>
-      jsx('nav', {
+    view: () => {
+      createEffect(() => {
+        const items = getItems();
+        void items.map((item) => item.id).join('\0');
+        untrack(() => {
+          pruneLinkRefs(items);
+          if (items.length === 0) {
+            listElement = null;
+            listHeight = 0;
+            linkRefs.clear();
+            syncActiveMarker(null);
+            setIndicator(hiddenIndicator());
+          }
+          scheduleListLayoutSync();
+        });
+      });
+      const root = jsx('nav', {
         className: settings.className.toc,
         'data-toc': 'root',
-        children: jsx('div', {
-          className: settings.className.list,
-          'data-toc-list': 'root',
-          children: For({
-            each: renderableItems,
-            key: (item: TocItem) => item.id,
-            children: (
-              itemAccessor: () => TocItem,
-              indexAccessor: () => number
-            ) =>
-              jsx('a', {
-                className: () => {
-                  const item = itemAccessor();
-                  return joinClasses(
-                    settings.className.link,
-                    `${settings.className.levelPrefix}${item.level}`,
-                    state.current.index === indexAccessor()
-                      ? settings.className.active
-                      : ''
-                  );
-                },
-                href: () => `#${itemAccessor().id}`,
-                'data-toc-index': () => String(indexAccessor()),
-                'data-toc-target': () => itemAccessor().id,
-                'data-active': () =>
-                  state.current.index === indexAccessor() ? '1' : '0',
-                onClick: (event: Event) => {
-                  event.preventDefault();
-                  scrollToItem(itemAccessor(), {
-                    activeIndex: indexAccessor(),
-                    updateHash: true,
-                  });
-                },
-                children: () => itemAccessor().text,
+      }) as HTMLElement;
+      insert(
+        root,
+        Show({
+          when: hasItems,
+          children: () => {
+            const titleElement = settings.title
+              ? jsx('div', {
+                  className: settings.className.title,
+                  'data-toc-title': '',
+                  children: translate('toc'),
+                })
+              : null;
+            const listView = jsx('div', {
+              ref: (element: HTMLElement) => {
+                listElement = element;
+                scheduleListLayoutSync();
+              },
+              className: settings.className.list,
+              'data-toc-list': 'root',
+              children: For({
+                each: renderableItems,
+                key: (item: TocItem) => item.id,
+                children: (itemAccessor: () => TocItem) =>
+                  jsx('a', {
+                    ref: (element: HTMLElement) =>
+                      bindLinkRef(itemAccessor(), element),
+                    className: settings.className.link,
+                    href: () => `#${itemAccessor().id}`,
+                    'data-toc-level': () => String(itemAccessor().level),
+                    onClick: (event: Event) => {
+                      event.preventDefault();
+                      const item = itemAccessor();
+                      scrollToItem(item, {
+                        activeIndex: getItems().findIndex(
+                          (current) => current.id === item.id
+                        ),
+                        updateHash: true,
+                      });
+                    },
+                    children: () => itemAccessor().text,
+                  }),
               }),
-          }),
-        }),
-      }) as HTMLElement,
+            }) as HTMLElement;
+            insert(
+              listView,
+              Show({
+                when: hasItems,
+                children: () =>
+                  jsx('div', {
+                    className: settings.className.indicator,
+                    'data-toc-indicator': '',
+                    hidden: () => !state.indicator.visible,
+                    style: () => ({
+                      pointerEvents: 'none',
+                      position: 'absolute',
+                      left: settings.indicator.left,
+                      top: `${state.indicator.top}px`,
+                      width: settings.indicator.width,
+                      height: `${state.indicator.height}px`,
+                      transition: `top ${state.indicator.duration}ms ${state.indicator.timingFunction}`,
+                      borderRadius: settings.indicator.radius,
+                      backgroundColor: settings.indicator.color,
+                    }),
+                  }),
+              })
+            );
+            return settings.title ? [titleElement, listView] : listView;
+          },
+        })
+      );
+      return root;
+    },
     onBuild(context) {
       target = requireContainer(settings.target, 'Toc.target');
       events.on('scroll', window, 'scroll', onScroll, { passive: true });
@@ -314,14 +649,20 @@ export function createToc(props: TocProps = {}): TocInstance {
     onDestroy() {
       if (runtime.frameId) cancelAnimationFrame(runtime.frameId);
       if (runtime.refreshFrameId) cancelAnimationFrame(runtime.refreshFrameId);
+      if (runtime.layoutFrameId) cancelAnimationFrame(runtime.layoutFrameId);
       runtime.frameId = 0;
       runtime.refreshFrameId = 0;
+      runtime.layoutFrameId = 0;
+      clearPendingScroll();
       runtime.ticking = false;
       runtime.refreshing = false;
       observer?.disconnect();
       observer = null;
       target = null;
       headings = [];
+      listElement = null;
+      listHeight = 0;
+      linkRefs.clear();
     },
   });
 

package/src/css/components.css

@@ -22,7 +22,6 @@
 @import url('./pagination.css');
 @import url('./card.css');
 @import url('./menu.css');
-@import url('./toc.css');
 @import url('./tree.css');
 @import url('./form.css');
 @import url('./toolbar.css');

package/src/css/themes/default/form.css

@@ -139,7 +139,7 @@
   }
 
   .input-inner-group .el-addon + .j-input {
-    padding-inline: var(--space);
+    padding-inline: 0 var(--space);
   }
 
   .input-inner-group .el-addon + .j-select {