@mindlogic-ai/logician-ui 5.0.0-alpha.12 → 5.0.0-alpha.13

package/src/components/NavList/NavList.translations.json

@@ -0,0 +1,9 @@
+{
+  "nav_list_opens_new_window": {
+    "ko": "새 창 열림",
+    "en": "opens in a new window",
+    "zh": "在新窗口中打开",
+    "ja": "新しいウィンドウで開く",
+    "es": "se abre en una ventana nueva"
+  }
+}

package/src/components/NavList/NavList.tsx

@@ -0,0 +1,160 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { chakra, mergeRefs } from '@chakra-ui/react';
+
+import { byOrientation, listStyles } from './NavList.styles';
+import { NavListProps } from './NavList.types';
+import { NavListContext } from './NavListContext';
+import { NavListGroup } from './NavListGroup';
+import { NavListItem } from './NavListItem';
+import { NavListSkeleton } from './NavListSkeleton';
+
+const useIsomorphicLayoutEffect =
+  typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+/**
+ * Bring the current row into a sideways-scrolling list's visible range, by
+ * moving that list's own `scrollLeft` only — never `scrollIntoView`, which
+ * also scrolls the page and every scrolling ancestor. A no-op when the list
+ * does not scroll sideways (a vertical rail) or the row is already in view.
+ */
+const revealCurrentHorizontally = (
+  list: HTMLUListElement,
+  current: Element
+) => {
+  if (list.scrollWidth <= list.clientWidth) return;
+  const listBox = list.getBoundingClientRect();
+  const rowBox = (current.closest('li') ?? current).getBoundingClientRect();
+  // Inside a closed group the row has no box; there is nothing to show.
+  if (rowBox.width === 0) return;
+  if (rowBox.left < listBox.left) {
+    list.scrollLeft -= listBox.left - rowBox.left;
+  } else if (rowBox.right > listBox.right) {
+    list.scrollLeft += rowBox.right - listBox.right;
+  }
+};
+
+/**
+ * A vertical list of rows for side navigation and in-page filter rails.
+ *
+ * Not tabs: there is no tablist, no `aria-selected` and no roving tabindex.
+ * Every row is its own link or button in the tab order, and the current one
+ * says so with `aria-current`.
+ *
+ * Named (`aria-label` / `aria-labelledby`), it is a `<nav>` landmark around
+ * the list; unnamed, it is just the list. A landmark should have a name once a
+ * page has more than one `nav`, and a list inside the app sidebar is already
+ * inside one — so the name is what decides whether this is a landmark of its
+ * own, rather than a flag the caller has to remember next to it.
+ *
+ * The ref and every other prop land on the `<ul>` either way — it is the flex
+ * and scroll container, so `gap`, `onScroll` and `ref.current.scrollLeft` mean
+ * the same thing whether or not the list is named.
+ */
+const NavListRoot = forwardRef<HTMLUListElement, NavListProps>(
+  (
+    {
+      orientation = 'vertical',
+      isCollapsed = false,
+      children,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      ...rest
+    },
+    ref
+  ) => {
+    const isLandmark = ariaLabel != null || ariaLabelledBy != null;
+    // A collapsed rail is a column of icons; it has no sideways form.
+    const axis = isCollapsed ? 'vertical' : orientation;
+    const listRef = useRef<HTMLUListElement>(null);
+    const mergedRef = useMemo(() => mergeRefs(ref, listRef), [ref]);
+
+    // Reveal the current row when it CHANGES (a row reports it from its own
+    // effect, so this works even when only that row re-rendered) and when the
+    // list is resized — a strip that just laid down at a breakpoint. Not on
+    // every render: a re-render must not snap back a strip the user scrolled.
+    const lastRevealed = useRef<Element | null>(null);
+    const reveal = useCallback((force = false) => {
+      const list = listRef.current;
+      const current = list?.querySelector('[data-current]');
+      if (!list || !current) return;
+      if (!force && current === lastRevealed.current) return;
+      lastRevealed.current = current;
+      revealCurrentHorizontally(list, current);
+    }, []);
+    useEffect(() => {
+      const list = listRef.current;
+      reveal();
+      if (!list || typeof ResizeObserver === 'undefined') return;
+      const observer = new ResizeObserver(() => reveal(true));
+      observer.observe(list);
+      return () => observer.disconnect();
+    }, [reveal]);
+
+    // Layout never reads this: rows, groups and the list inherit `direction`
+    // in CSS, so a right-to-left server render is right on its first paint.
+    // Only the rows' TOOLTIPS need it in JS — zag stamps `dir` on their
+    // portalled content from Ark's locale, and a popper placement is
+    // physical — and a tooltip only opens after hydration, when this is known.
+    const [tooltipDir, setTooltipDir] = useState<'ltr' | 'rtl'>('ltr');
+    useIsomorphicLayoutEffect(() => {
+      const list = listRef.current;
+      if (!list) return;
+      const next = getComputedStyle(list).direction === 'rtl' ? 'rtl' : 'ltr';
+      if (next !== tooltipDir) setTooltipDir(next);
+    });
+
+    const context = useMemo(
+      () => ({
+        orientation: axis,
+        isCollapsed,
+        tooltipDir,
+        revealCurrent: reveal,
+      }),
+      [axis, isCollapsed, tooltipDir, reveal]
+    );
+
+    const list = (
+      <chakra.ul
+        ref={mergedRef}
+        {...listStyles(axis)}
+        overflowX={byOrientation(axis, 'visible', 'auto')}
+        overflowY={byOrientation(axis, 'visible', 'hidden')}
+        {...rest}
+      >
+        {children}
+      </chakra.ul>
+    );
+
+    return (
+      <NavListContext.Provider value={context}>
+        {isLandmark ? (
+          <chakra.nav
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledBy}
+            minW={0}
+          >
+            {list}
+          </chakra.nav>
+        ) : (
+          list
+        )}
+      </NavListContext.Provider>
+    );
+  }
+);
+
+NavListRoot.displayName = 'NavList';
+
+export const NavList = Object.assign(NavListRoot, {
+  Item: NavListItem,
+  Group: NavListGroup,
+  Skeleton: NavListSkeleton,
+});

package/src/components/NavList/NavList.types.ts

@@ -0,0 +1,145 @@
+import type { MouseEventHandler, ReactNode } from 'react';
+import type { HTMLChakraProps } from '@chakra-ui/react';
+
+export type NavListOrientation = 'vertical' | 'horizontal';
+
+type NavListBreakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/**
+ * One orientation, or one per breakpoint. The media-template rails and the
+ * Drive source rail lie down into a sideways-scrolling row below `md`:
+ *
+ * ```tsx
+ * <NavList orientation={{ base: 'horizontal', md: 'vertical' }} />
+ * ```
+ *
+ * The switch is pure CSS (one rule per breakpoint), so it never renders the
+ * wrong axis first and corrects itself after hydration.
+ */
+export type NavListResponsiveOrientation =
+  | NavListOrientation
+  | Partial<Record<NavListBreakpoint, NavListOrientation>>;
+
+export type NavListProps = Omit<HTMLChakraProps<'ul'>, 'children'> & {
+  children?: ReactNode;
+  /**
+   * `vertical` is a rail; `horizontal` is a single row that scrolls sideways
+   * instead of wrapping. Accepts a per-breakpoint object.
+   * @default 'vertical'
+   */
+  orientation?: NavListResponsiveOrientation;
+  /**
+   * Naming the list makes it a `<nav>` landmark around the list. Leave it off
+   * when the list already sits inside a named landmark (the app sidebar) — a
+   * second, unnamed `nav` is noise in the landmark menu.
+   */
+  'aria-label'?: string;
+  /** As `aria-label`, pointing at a visible heading. Also makes it a `<nav>`. */
+  'aria-labelledby'?: string;
+  /**
+   * The collapsed rail: every row is a 40px icon-only square whose label is
+   * still its accessible name (visually hidden) and shows as a tooltip on
+   * hover and keyboard focus. `trailingVisual`, `trailingAction` and group
+   * titles are hidden; a collapsible group shows its rows. Every row needs a
+   * `leadingVisual` in this mode. Vertical only.
+   * @default false
+   */
+  isCollapsed?: boolean;
+};
+
+export type NavListTrailingActionVisibility = 'always' | 'hover';
+
+export type NavListItemProps = Omit<
+  HTMLChakraProps<'a'>,
+  'children' | 'onClick' | 'aria-current' | 'asChild'
+> & {
+  /**
+   * The label. With `asChild`, the single link element (e.g. `next/link`)
+   * whose own children are the label.
+   */
+  children?: ReactNode;
+  /** Renders an `<a>`. Without `href` (and without `asChild`) the row is a `<button>`. */
+  href?: string;
+  /**
+   * Merge the row onto the one child element instead of rendering an `<a>` —
+   * for a router link: `<NavList.Item asChild><NextLink href="/x">X</NextLink></NavList.Item>`.
+   * The row is treated as a link.
+   */
+  asChild?: boolean;
+  onClick?: MouseEventHandler<HTMLElement>;
+  /**
+   * This row is where the user is: `aria-current="page"` on a link,
+   * `aria-current="true"` on a button (the active filter of a rail). Shown as
+   * an ink label, bold, on a `bg.emphasized` fill.
+   */
+  isCurrent?: boolean;
+  /**
+   * A button becomes `disabled`. A link — `asChild` included — is rendered
+   * as an `<a role="link" aria-disabled="true">` with no `href`: still
+   * announced as a link, out of the tab order, and nothing to open in a new tab.
+   */
+  isDisabled?: boolean;
+  /** Icon before the label. Decorative — the label names the row. */
+  leadingVisual?: ReactNode;
+  /** Count or badge after the label, in muted text. Read as part of the row's name. */
+  trailingVisual?: ReactNode;
+  /**
+   * A separate control beside the row (more-menu, remove), e.g. an
+   * `IconButton` with its own `aria-label`. It is a sibling of the row, never
+   * inside it, so there is no interactive element nested in another.
+   */
+  trailingAction?: ReactNode;
+  /**
+   * `hover`: the trailing action is transparent until the row is hovered, or
+   * focus is anywhere in the row, or the action's own menu is open
+   * (`aria-expanded="true"` / `data-state="open"` inside it). It is never
+   * removed, so Tab still reaches it — focusing it is what reveals it. Always
+   * shown on touch screens (`hover: none`), where there is no hover to reveal it.
+   * @default 'always'
+   */
+  trailingActionVisibility?: NavListTrailingActionVisibility;
+  /**
+   * A tooltip that adds to the label — a description, or why a row is
+   * disabled. It is also the row's accessible DESCRIPTION, through a hidden
+   * element that is referenced whether or not the tooltip is open — so a
+   * disabled row, which cannot take focus, still says why. It must not repeat
+   * the label. In a collapsed list it shows under the label.
+   *
+   * Label tooltips need no prop: a label cut off by the ellipsis shows itself
+   * in full on hover/focus, and every row of a collapsed list shows its label.
+   * Those are not wired as a description, because they would read the name twice.
+   */
+  tooltip?: ReactNode;
+};
+
+export type NavListGroupProps = Omit<
+  HTMLChakraProps<'li'>,
+  'children' | 'title'
+> & {
+  children?: ReactNode;
+  /**
+   * Text above the group's rows, in overline style. Not interactive and not a
+   * heading element — it names the group's list (`aria-labelledby`), so it
+   * does not add a level to the page outline.
+   */
+  title?: ReactNode;
+  /**
+   * The title becomes a `<button aria-expanded>` that shows and hides the
+   * group's rows. Needs a `title`. Persisting the state (local storage, a
+   * store) is the caller's: pass `isOpen` + `onOpenChange`.
+   * @default false
+   */
+  isCollapsible?: boolean;
+  /** Controlled open state of a collapsible group. */
+  isOpen?: boolean;
+  /** Uncontrolled initial state of a collapsible group. @default true */
+  defaultOpen?: boolean;
+  onOpenChange?: (isOpen: boolean) => void;
+};
+
+export type NavListSkeletonProps = Omit<HTMLChakraProps<'ul'>, 'children'> & {
+  /** How many placeholder rows. @default 5 */
+  count?: number;
+  /** Lay the placeholders out like the list they stand in for. @default 'vertical' */
+  orientation?: NavListResponsiveOrientation;
+};