@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/hooks/useAnchoredPosition.ts

@@ -0,0 +1,176 @@
+import {useCallback, useEffect, useState, type RefObject} from 'react';
+
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect.js';
+
+/** Side of the anchor a floating surface prefers to occupy. */
+export type Placement = 'bottom' | 'left' | 'right' | 'top';
+
+/** How a floating surface lines up along the anchor's cross axis. */
+export type Alignment = 'center' | 'end' | 'start';
+
+/** Options controlling where a floating surface settles. */
+export interface AnchoredPositionOptions {
+  readonly alignment?: Alignment;
+  readonly offset?: number;
+  readonly placement?: Placement;
+}
+
+/** Resolved viewport coordinates for a floating surface. */
+export interface AnchoredPosition {
+  readonly left: number;
+  readonly placement: Placement;
+  readonly top: number;
+}
+
+/** The measured position plus the ref that feeds it. */
+export interface AnchoredPositionResult {
+  readonly position: AnchoredPosition | undefined;
+  readonly surface: HTMLElement | null;
+  readonly surfaceRef: (node: HTMLElement | null) => void;
+}
+
+const opposite: Record<Placement, Placement> = {
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+  top: 'bottom',
+};
+
+function alignAcross(
+  anchorStart: number,
+  anchorSize: number,
+  surfaceSize: number,
+  alignment: Alignment,
+) {
+  if (alignment === 'center') {
+    return anchorStart + (anchorSize - surfaceSize) / 2;
+  }
+  return alignment === 'start'
+    ? anchorStart
+    : anchorStart + anchorSize - surfaceSize;
+}
+
+function place(
+  anchor: DOMRect,
+  surface: DOMRect,
+  placement: Placement,
+  alignment: Alignment,
+  offset: number,
+) {
+  switch (placement) {
+    case 'top':
+      return {
+        left: alignAcross(anchor.left, anchor.width, surface.width, alignment),
+        top: anchor.top - surface.height - offset,
+      };
+    case 'bottom':
+      return {
+        left: alignAcross(anchor.left, anchor.width, surface.width, alignment),
+        top: anchor.bottom + offset,
+      };
+    case 'left':
+      return {
+        left: anchor.left - surface.width - offset,
+        top: alignAcross(anchor.top, anchor.height, surface.height, alignment),
+      };
+    case 'right':
+      return {
+        left: anchor.right + offset,
+        top: alignAcross(anchor.top, anchor.height, surface.height, alignment),
+      };
+  }
+}
+
+function fitsInViewport(
+  {left, top}: {left: number; top: number},
+  surface: DOMRect,
+) {
+  return (
+    left >= 0 &&
+    top >= 0 &&
+    left + surface.width <= window.innerWidth &&
+    top + surface.height <= window.innerHeight
+  );
+}
+
+function clampToViewport(
+  {left, top}: {left: number; top: number},
+  surface: DOMRect,
+) {
+  return {
+    left: Math.max(0, Math.min(left, window.innerWidth - surface.width)),
+    top: Math.max(0, Math.min(top, window.innerHeight - surface.height)),
+  };
+}
+
+/**
+ * Positions a floating surface against an anchor, flipping to the opposite
+ * side when the preferred one would leave the viewport and clamping whatever
+ * survives back inside it. Recomputed on scroll and resize while open.
+ *
+ * The surface is tracked through a callback ref rather than a plain ref
+ * because portalled surfaces mount after the caller renders; a ref would
+ * still read `null` when the first measurement runs.
+ */
+export function useAnchoredPosition(
+  anchorRef: RefObject<HTMLElement | null>,
+  open: boolean,
+  {
+    alignment = 'center',
+    offset = 8,
+    placement = 'bottom',
+  }: AnchoredPositionOptions = {},
+): AnchoredPositionResult {
+  const [position, setPosition] = useState<AnchoredPosition | undefined>(
+    undefined,
+  );
+  const [surfaceElement, setSurfaceElement] = useState<HTMLElement | null>(
+    null,
+  );
+
+  const measure = useCallback(() => {
+    const anchorElement = anchorRef.current;
+    if (!anchorElement || !surfaceElement) {
+      return;
+    }
+
+    const anchor = anchorElement.getBoundingClientRect();
+    const surface = surfaceElement.getBoundingClientRect();
+
+    const preferred = place(anchor, surface, placement, alignment, offset);
+    const resolved = fitsInViewport(preferred, surface)
+      ? {...preferred, placement}
+      : {
+          ...place(anchor, surface, opposite[placement], alignment, offset),
+          placement: opposite[placement],
+        };
+
+    setPosition({
+      ...clampToViewport(resolved, surface),
+      placement: resolved.placement,
+    });
+  }, [alignment, anchorRef, offset, placement, surfaceElement]);
+
+  useIsomorphicLayoutEffect(() => {
+    if (open) {
+      measure();
+    } else {
+      setPosition(undefined);
+    }
+  }, [measure, open]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    window.addEventListener('resize', measure);
+    window.addEventListener('scroll', measure, true);
+    return () => {
+      window.removeEventListener('resize', measure);
+      window.removeEventListener('scroll', measure, true);
+    };
+  }, [measure, open]);
+
+  return {position, surface: surfaceElement, surfaceRef: setSurfaceElement};
+}

package/src/hooks/useAnnounce.ts

@@ -0,0 +1,49 @@
+import {useCallback, useEffect, useRef} from 'react';
+
+/** Urgency levels a live-region announcement can claim. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+
+const regionStyle =
+  'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0';
+
+/**
+ * Returns a function that speaks a message through an owned live region.
+ * The region is created lazily and removed with the component that owns it.
+ */
+export function useAnnounce(): (
+  message: string,
+  politeness?: AnnouncePoliteness,
+) => void {
+  const regionRef = useRef<HTMLElement | null>(null);
+
+  useEffect(
+    () => () => {
+      regionRef.current?.remove();
+      regionRef.current = null;
+    },
+    [],
+  );
+
+  return useCallback(
+    (message: string, politeness: AnnouncePoliteness = 'polite') => {
+      if (typeof document === 'undefined' || message.trim() === '') {
+        return;
+      }
+
+      let region = regionRef.current;
+      if (!region) {
+        region = document.createElement('div');
+        region.setAttribute('role', 'status');
+        region.setAttribute('style', regionStyle);
+        document.body.append(region);
+        regionRef.current = region;
+      }
+
+      region.setAttribute('aria-live', politeness);
+      // Clearing first forces assistive technology to re-read an identical message.
+      region.textContent = '';
+      region.textContent = message;
+    },
+    [],
+  );
+}

package/src/hooks/useClipboard.ts

@@ -0,0 +1,48 @@
+import {useCallback, useEffect, useRef, useState} from 'react';
+
+/** Result of a clipboard hook: the copy action and its recent outcome. */
+export interface ClipboardState {
+  readonly copied: boolean;
+  readonly copy: (text: string) => Promise<boolean>;
+}
+
+/**
+ * Copies text and reports success for `resetAfterMs`, so a caller can show a
+ * confirmation without owning its own timer.
+ */
+export function useClipboard(resetAfterMs = 2000): ClipboardState {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(
+    () => () => {
+      clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    async (text: string) => {
+      if (typeof navigator === 'undefined' || !navigator.clipboard) {
+        return false;
+      }
+
+      try {
+        await navigator.clipboard.writeText(text);
+      } catch {
+        setCopied(false);
+        return false;
+      }
+
+      setCopied(true);
+      clearTimeout(timer.current);
+      timer.current = setTimeout(() => {
+        setCopied(false);
+      }, resetAfterMs);
+      return true;
+    },
+    [resetAfterMs],
+  );
+
+  return {copied, copy};
+}

package/src/hooks/useDevWarning.ts

@@ -0,0 +1,24 @@
+import {useEffect, useRef} from 'react';
+
+function isProduction() {
+  return (
+    typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production'
+  );
+}
+
+/**
+ * Reports a broken component contract once per mount during development.
+ * Production builds stay silent so hosts never pay for the check.
+ */
+export function useDevWarning(condition: boolean, message: string): void {
+  const warned = useRef(false);
+
+  useEffect(() => {
+    if (isProduction() || !condition || warned.current) {
+      return;
+    }
+
+    warned.current = true;
+    console.warn(message);
+  }, [condition, message]);
+}

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,62 @@
+import {useEffect} from 'react';
+
+import {focusableElements} from './focusableSelector.js';
+
+/**
+ * Confines Tab and Shift+Tab to the descendants of `container` while `active`
+ * is true, then returns focus to whatever held it before the trap opened.
+ *
+ * The container is passed as an element rather than a ref because portalled
+ * surfaces mount after their owner renders; a ref would still read `null`
+ * when this effect first runs, and the trap would never arm.
+ */
+export function useFocusTrap(
+  container: HTMLElement | null,
+  active: boolean,
+): void {
+  useEffect(() => {
+    if (!active || !container) {
+      return;
+    }
+
+    const previous =
+      document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
+
+    const [initial] = focusableElements(container);
+    (initial ?? container).focus({preventScroll: true});
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key !== 'Tab' || !container) {
+        return;
+      }
+
+      const focusable = focusableElements(container);
+      if (focusable.length === 0) {
+        event.preventDefault();
+        return;
+      }
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      const target = document.activeElement;
+
+      if (event.shiftKey && (target === first || !container.contains(target))) {
+        event.preventDefault();
+        last?.focus({preventScroll: true});
+        return;
+      }
+      if (!event.shiftKey && target === last) {
+        event.preventDefault();
+        first?.focus({preventScroll: true});
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown, true);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown, true);
+      previous?.focus({preventScroll: true});
+    };
+  }, [active, container]);
+}

package/src/hooks/useHotkeys.ts

@@ -0,0 +1,81 @@
+import {useEffect, useRef} from 'react';
+
+/**
+ * Maps a normalized shortcut to its handler. Combinations use `+` and the
+ * `mod` alias, which resolves to Command on Apple platforms and Control
+ * everywhere else: `mod+k`, `shift+?`, `Escape`.
+ */
+export type HotkeyBindings = Readonly<
+  Record<string, (event: KeyboardEvent) => void>
+>;
+
+/** Options controlling when a hotkey map listens. */
+export interface HotkeyOptions {
+  readonly enabled?: boolean;
+}
+
+function isApplePlatform() {
+  return (
+    typeof navigator !== 'undefined' &&
+    /Mac|iPhone|iPad/u.test(navigator.platform)
+  );
+}
+
+function describe(event: KeyboardEvent) {
+  const parts: string[] = [];
+  const mod = isApplePlatform() ? event.metaKey : event.ctrlKey;
+
+  if (mod) parts.push('mod');
+  if (event.altKey) parts.push('alt');
+  if (event.shiftKey) parts.push('shift');
+  parts.push(event.key.toLowerCase());
+
+  return parts.join('+');
+}
+
+const modifierOrder = ['mod', 'alt', 'shift'];
+
+// Non-modifiers rank last so `mod+k` and `K+MOD` describe the same shortcut.
+function rank(part: string) {
+  const index = modifierOrder.indexOf(part);
+  return index === -1 ? modifierOrder.length : index;
+}
+
+function normalize(binding: string) {
+  return binding
+    .split('+')
+    .map((part) => part.trim().toLowerCase())
+    .sort((left, right) => rank(left) - rank(right))
+    .join('+');
+}
+
+/** Runs a handler when its shortcut fires anywhere in the document. */
+export function useHotkeys(
+  bindings: HotkeyBindings,
+  {enabled = true}: HotkeyOptions = {},
+): void {
+  const bindingsRef = useRef(bindings);
+  bindingsRef.current = bindings;
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    function handleKeyDown(event: KeyboardEvent) {
+      const pressed = describe(event);
+
+      for (const [binding, handler] of Object.entries(bindingsRef.current)) {
+        if (normalize(binding) === pressed) {
+          handler(event);
+          return;
+        }
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [enabled]);
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,8 @@
+import {useEffect, useLayoutEffect} from 'react';
+
+/**
+ * Runs layout work before paint in the browser and falls back to a plain
+ * effect on the server, where React cannot run layout effects at all.
+ */
+export const useIsomorphicLayoutEffect =
+  typeof window === 'undefined' ? useEffect : useLayoutEffect;

package/src/hooks/useListFocus.ts

@@ -0,0 +1,75 @@
+import {useCallback, type KeyboardEvent, type RefObject} from 'react';
+
+import {reachableElements} from './focusableSelector.js';
+
+/** Axis a roving-focus collection reads its arrow keys along. */
+export type ListOrientation = 'horizontal' | 'vertical';
+
+/** Options controlling how roving focus moves through a collection. */
+export interface ListFocusOptions {
+  readonly loop?: boolean;
+  readonly orientation?: ListOrientation;
+}
+
+const nextKeys: Record<ListOrientation, string> = {
+  horizontal: 'ArrowRight',
+  vertical: 'ArrowDown',
+};
+
+const previousKeys: Record<ListOrientation, string> = {
+  horizontal: 'ArrowLeft',
+  vertical: 'ArrowUp',
+};
+
+function clamp(index: number, length: number, loop: boolean) {
+  if (loop) {
+    return (index + length) % length;
+  }
+  return Math.min(Math.max(index, 0), length - 1);
+}
+
+/**
+ * Moves focus through a collection with arrow, Home, and End keys so the
+ * collection occupies a single stop in the page tab order.
+ */
+export function useListFocus(
+  ref: RefObject<HTMLElement | null>,
+  {loop = true, orientation = 'vertical'}: ListFocusOptions = {},
+) {
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      const container = ref.current;
+      if (!container) {
+        return;
+      }
+
+      const items = reachableElements(container);
+      if (items.length === 0) {
+        return;
+      }
+
+      const current = items.indexOf(document.activeElement as HTMLElement);
+      let target: number | undefined;
+
+      if (event.key === nextKeys[orientation]) {
+        target = clamp(current + 1, items.length, loop);
+      } else if (event.key === previousKeys[orientation]) {
+        target = clamp(current - 1, items.length, loop);
+      } else if (event.key === 'Home') {
+        target = 0;
+      } else if (event.key === 'End') {
+        target = items.length - 1;
+      }
+
+      if (target === undefined) {
+        return;
+      }
+
+      event.preventDefault();
+      items[target]?.focus({preventScroll: true});
+    },
+    [loop, orientation, ref],
+  );
+
+  return {onKeyDown};
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,35 @@
+import {useCallback, useSyncExternalStore} from 'react';
+
+function supportsMatchMedia() {
+  return (
+    typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+  );
+}
+
+/**
+ * Tracks a CSS media query as React state. Server renders report `false` so
+ * the first client paint stays consistent with the markup React sent.
+ */
+export function useMediaQuery(query: string): boolean {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!supportsMatchMedia()) {
+        return () => {};
+      }
+
+      const list = window.matchMedia(query);
+      list.addEventListener('change', onStoreChange);
+      return () => {
+        list.removeEventListener('change', onStoreChange);
+      };
+    },
+    [query],
+  );
+
+  const getSnapshot = useCallback(
+    () => (supportsMatchMedia() ? window.matchMedia(query).matches : false),
+    [query],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}

package/src/hooks/useScrollLock.ts

@@ -0,0 +1,28 @@
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect.js';
+
+/**
+ * Freezes document scrolling while `active` is true and compensates for the
+ * scrollbar it removes, so the page behind an overlay does not shift.
+ */
+export function useScrollLock(active: boolean): void {
+  useIsomorphicLayoutEffect(() => {
+    if (!active) {
+      return;
+    }
+
+    const {body, documentElement} = document;
+    const previousOverflow = body.style.overflow;
+    const previousPaddingInlineEnd = body.style.paddingInlineEnd;
+    const scrollbarWidth = window.innerWidth - documentElement.clientWidth;
+
+    body.style.overflow = 'hidden';
+    if (scrollbarWidth > 0) {
+      body.style.paddingInlineEnd = `${scrollbarWidth}px`;
+    }
+
+    return () => {
+      body.style.overflow = previousOverflow;
+      body.style.paddingInlineEnd = previousPaddingInlineEnd;
+    };
+  }, [active]);
+}

package/src/i18n/Internationalization.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const internationalizationProviderDoc = {
+  name: 'InternationalizationProvider',
+  description: 'Supplies the locale, writing direction, and system strings.',
+  props: [
+    {name: 'children', description: 'Supplies the tree that reads the locale.'},
+    {name: 'direction', description: 'Selects the writing direction.'},
+    {name: 'locale', description: 'Names the active locale.'},
+    {name: 'messages', description: 'Replaces every string the system speaks.'},
+  ],
+  inheritedProps: ['None; the provider owns its language wrapper'],
+  example:
+    '<InternationalizationProvider direction="rtl" locale="ar" messages={ar}>…</InternationalizationProvider>',
+  storyId: 'core-internationalization-provider--default',
+} satisfies ComponentDoc;

package/src/i18n/Internationalization.tsx

@@ -0,0 +1,66 @@
+import {createContext, useContext, useMemo, type ReactNode} from 'react';
+
+import {defaultMessages, type Messages} from './messages.js';
+
+/** The locale settings and strings available to descendants. */
+export interface InternationalizationValue {
+  readonly direction: 'ltr' | 'rtl';
+  readonly locale: string;
+  readonly messages: Messages;
+}
+
+const InternationalizationContext = createContext<
+  InternationalizationValue | undefined
+>(undefined);
+
+/** Props for the locale and string provider. */
+export interface InternationalizationProviderProps {
+  readonly children: ReactNode;
+  readonly direction?: 'ltr' | 'rtl';
+  readonly locale?: string;
+  readonly messages?: Messages;
+}
+
+/**
+ * Supplies the locale, writing direction, and strings the system speaks. The
+ * library ships English and owns no translation pipeline; a host replaces the
+ * whole message set for another language.
+ */
+export function InternationalizationProvider({
+  children,
+  direction = 'ltr',
+  locale = 'en',
+  messages = defaultMessages,
+}: InternationalizationProviderProps) {
+  const value = useMemo(
+    () => ({direction, locale, messages}),
+    [direction, locale, messages],
+  );
+
+  return (
+    <InternationalizationContext.Provider value={value}>
+      <div dir={direction} lang={locale}>
+        {children}
+      </div>
+    </InternationalizationContext.Provider>
+  );
+}
+
+/**
+ * Reads the active locale settings. Without a provider it reports the built-in
+ * English defaults, so a component never has to guard for a missing host.
+ */
+export function useInternationalization(): InternationalizationValue {
+  return (
+    useContext(InternationalizationContext) ?? {
+      direction: 'ltr',
+      locale: 'en',
+      messages: defaultMessages,
+    }
+  );
+}
+
+/** Reads one string by key from the active message set. */
+export function useMessage(key: keyof Messages): string {
+  return useInternationalization().messages[key];
+}

package/src/i18n/index.ts

@@ -0,0 +1,8 @@
+export {
+  InternationalizationProvider,
+  useInternationalization,
+  useMessage,
+  type InternationalizationProviderProps,
+  type InternationalizationValue,
+} from './Internationalization.js';
+export {defaultMessages, type Messages} from './messages.js';