@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Overlay/Overlay.tsx

@@ -0,0 +1,122 @@
+import * as stylex from '@stylexjs/stylex';
+import {useEffect, useState, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFocusTrap} from '../hooks/useFocusTrap.js';
+import {useScrollLock} from '../hooks/useScrollLock.js';
+import {Layer} from '../Layer/index.js';
+
+const scrimEnter = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
+const styles = stylex.create({
+  scrim: {
+    alignItems: 'center',
+    animationDuration: semanticTokens.durationFast,
+    animationName: {
+      default: scrimEnter,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingEmphasized,
+    backgroundColor: semanticTokens.colorScrim,
+    display: 'flex',
+    inset: 0,
+    justifyContent: 'center',
+    padding: semanticTokens.spacingLg,
+    position: 'fixed',
+  },
+  bare: {
+    backgroundColor: 'transparent',
+    padding: 0,
+    pointerEvents: 'none',
+  },
+  surface: {
+    maxHeight: '100%',
+    maxWidth: '100%',
+    outlineStyle: 'none',
+    pointerEvents: 'auto',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+});
+
+/** Props for the dismissal, focus, and scroll behaviour behind modal surfaces. */
+export interface OverlayProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly dismissOnOutsideClick?: boolean;
+  readonly lockScroll?: boolean;
+  readonly onDismiss?: () => void;
+  readonly open: boolean;
+  readonly scrim?: boolean;
+  readonly trapFocus?: boolean;
+}
+
+/**
+ * Owns the behaviour every modal surface repeats: an optional scrim, Escape
+ * and outside-click dismissal, a focus trap, and a scroll lock. It carries no
+ * role of its own so the caller names the surface it wraps.
+ */
+export function Overlay({
+  children,
+  dismissOnOutsideClick = true,
+  lockScroll = true,
+  onDismiss,
+  open,
+  scrim = true,
+  trapFocus = true,
+  ...props
+}: OverlayProps) {
+  const [surface, setSurface] = useState<HTMLDivElement | null>(null);
+
+  useFocusTrap(surface, open && trapFocus);
+  useScrollLock(open && lockScroll);
+
+  useEffect(() => {
+    if (!open || !onDismiss) {
+      return;
+    }
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === 'Escape') {
+        event.stopPropagation();
+        onDismiss?.();
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [onDismiss, open]);
+
+  if (!open) {
+    return null;
+  }
+
+  return (
+    <Layer>
+      <div
+        {...props}
+        onMouseDown={(event) => {
+          if (dismissOnOutsideClick && event.target === event.currentTarget) {
+            onDismiss?.();
+          }
+        }}
+        {...stylex.props(styles.scrim, !scrim && styles.bare)}
+      >
+        <div ref={setSurface} tabIndex={-1} {...stylex.props(styles.surface)}>
+          {children}
+        </div>
+      </div>
+    </Layer>
+  );
+}

package/src/Overlay/index.ts

@@ -0,0 +1 @@
+export {Overlay, type OverlayProps} from './Overlay.js';

package/src/Pagination/Pagination.doc.ts

@@ -0,0 +1,28 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const paginationDoc = {
+  name: 'Pagination',
+  description: 'Moves between pages of a bounded result set.',
+  props: [
+    {name: 'label', description: 'Names the navigation landmark.'},
+    {
+      name: 'onChange',
+      description: 'Receives the newly requested page number.',
+    },
+    {
+      name: 'page',
+      description: 'Identifies the current page, counting from one.',
+    },
+    {name: 'pageCount', description: 'States how many pages exist in total.'},
+    {
+      name: 'siblingCount',
+      description:
+        'Sets how many pages stay visible either side of the current one.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLElement> except children, className, and onChange',
+  ],
+  example: '<Pagination onChange={setPage} page={page} pageCount={12} />',
+  storyId: 'core-pagination--default',
+} satisfies ComponentDoc;

package/src/Pagination/Pagination.tsx

@@ -0,0 +1,259 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useInternationalization} from '../i18n/index.js';
+import {Icon} from '../Icon/index.js';
+
+const styles = stylex.create({
+  nav: {fontFamily: semanticTokens.fontFamilyBody},
+  // A run of figures across the foot of a page, spaced like one: the strip is
+  // read as a line of type, so the steps stand the same distance from the
+  // numbers as the numbers stand from each other.
+  list: {
+    alignItems: 'center',
+    display: 'flex',
+    gap: semanticTokens.spacingMd,
+    listStyleType: 'none',
+    marginBlock: 0,
+    paddingInlineStart: 0,
+  },
+  // Previous and next are two more entries in that line, not two buttons
+  // bracketing it. A boxed control at either end turns a quiet footer into a
+  // toolbar, and the foot of a table is the last place that belongs — so the
+  // step carries no surface and no edge, and takes the figures' face with the
+  // numbers it sits beside.
+  step: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    height: semanticTokens.sizeControlSm,
+    justifyContent: 'center',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    minWidth: semanticTokens.sizeControlSm,
+    paddingInline: semanticTokens.spacingXs,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':disabled': {
+      color: semanticTokens.colorDisabledText,
+      cursor: 'default',
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':active:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayActive,
+      color: semanticTokens.colorText,
+    },
+    ':hover:not(:disabled):not(:active)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  // A page number is a link in a row of links, not a control with an edge:
+  // the strip stays quiet until one number is marked as the current page.
+  //
+  // That mark is a hairline rule under the figure, not the 2px one a tab
+  // takes. Pagination is a subordinate rank — it says where you are inside a
+  // view, never which view you are in — and a 2px underline in the foot of a
+  // table competes with the tab strip at the top of it.
+  //
+  // It is also a figure, so it is set in the mono face with tabular figures.
+  // Proportional digits make 8 wider than 1, and a strip whose numbers change
+  // width as the reader walks through the pages wobbles under the cursor.
+  page: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderBlockEndColor: 'transparent',
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    borderBlockStartStyle: 'none',
+    borderBlockStartWidth: 0,
+    borderInlineStyle: 'none',
+    borderInlineWidth: 0,
+    borderRadius: semanticTokens.radiusElement,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: semanticTokens.fontWeightRegular,
+    height: semanticTokens.sizeControlSm,
+    justifyContent: 'center',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    minWidth: semanticTokens.sizeControlSm,
+    paddingInline: semanticTokens.spacingXs,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  unselected: {
+    ':active:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayActive,
+      color: semanticTokens.colorText,
+    },
+    ':hover:not(:disabled):not(:active)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  current: {
+    borderBlockEndColor: semanticTokens.colorText,
+    color: semanticTokens.colorText,
+    cursor: 'default',
+    fontWeight: semanticTokens.fontWeightMedium,
+  },
+  // The gap sits in the run of figures, so it takes the figures' face and the
+  // third rank of ink: it is context, not a page you can go to.
+  ellipsis: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingMono,
+    paddingInline: semanticTokens.spacingXs,
+  },
+});
+
+// Keeps the first page, the last page, and a window around the current one.
+function pageWindow(page: number, pageCount: number, span: number) {
+  const pages = new Set<number>([1, pageCount]);
+  for (let offset = -span; offset <= span; offset += 1) {
+    const candidate = page + offset;
+    if (candidate >= 1 && candidate <= pageCount) {
+      pages.add(candidate);
+    }
+  }
+
+  const ordered = [...pages].sort((left, right) => left - right);
+  const entries: Array<number | 'gap'> = [];
+  let previous: number | undefined;
+
+  for (const value of ordered) {
+    if (previous !== undefined && value - previous > 1) {
+      entries.push('gap');
+    }
+    entries.push(value);
+    previous = value;
+  }
+
+  return entries;
+}
+
+/** Props for page-number navigation over a bounded result set. */
+export interface PaginationProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'className' | 'onChange'
+> {
+  readonly label?: string;
+  readonly onChange: (page: number) => void;
+  readonly page: number;
+  readonly pageCount: number;
+  readonly siblingCount?: number;
+}
+
+/**
+ * Moves between pages of a bounded result set. Use it only when a reader
+ * needs to jump to a specific page; otherwise prefer cursor navigation.
+ */
+export function Pagination({
+  label = 'Pagination',
+  onChange,
+  page,
+  pageCount,
+  siblingCount = 1,
+  ...props
+}: PaginationProps) {
+  const {messages} = useInternationalization();
+  const entries = pageWindow(page, pageCount, siblingCount);
+
+  return (
+    <nav {...props} aria-label={label} {...stylex.props(styles.nav)}>
+      <ul {...stylex.props(styles.list)}>
+        <li>
+          <button
+            aria-label={messages.paginationPrevious}
+            disabled={page <= 1}
+            onClick={() => {
+              onChange(page - 1);
+            }}
+            {...stylex.props(styles.step)}
+            type="button"
+          >
+            <Icon>
+              <path
+                d="m15 6-6 6 6 6"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </Icon>
+          </button>
+        </li>
+        {entries.map((entry, index) =>
+          entry === 'gap' ? (
+            <li key={`gap-${index}`} {...stylex.props(styles.ellipsis)}>
+              <span aria-hidden="true">…</span>
+            </li>
+          ) : (
+            <li key={entry}>
+              <button
+                {...(entry === page ? {'aria-current': 'page'} : {})}
+                aria-label={`Page ${entry}`}
+                onClick={() => {
+                  onChange(entry);
+                }}
+                {...stylex.props(
+                  styles.page,
+                  entry === page ? styles.current : styles.unselected,
+                )}
+                type="button"
+              >
+                {entry}
+              </button>
+            </li>
+          ),
+        )}
+        <li>
+          <button
+            aria-label={messages.paginationNext}
+            disabled={page >= pageCount}
+            onClick={() => {
+              onChange(page + 1);
+            }}
+            {...stylex.props(styles.step)}
+            type="button"
+          >
+            <Icon>
+              <path
+                d="m9 6 6 6-6 6"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </Icon>
+          </button>
+        </li>
+      </ul>
+    </nav>
+  );
+}

package/src/Pagination/index.ts

@@ -0,0 +1 @@
+export {Pagination, type PaginationProps} from './Pagination.js';

package/src/Popover/Popover.doc.ts

@@ -0,0 +1,27 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const popoverDoc = {
+  name: 'Popover',
+  description: 'Floats content beside an anchor without blocking the page.',
+  props: [
+    {
+      name: 'alignment',
+      description: 'Lines the surface up along the cross axis.',
+    },
+    {name: 'anchorRef', description: 'References the element to float beside.'},
+    {name: 'children', description: 'Supplies the floating content.'},
+    {name: 'offset', description: 'Sets the gap between anchor and surface.'},
+    {name: 'onDismiss', description: 'Runs on Escape or an outside click.'},
+    {name: 'open', description: 'Controls whether the surface renders.'},
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the anchor.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example:
+    '<Popover anchorRef={triggerRef} onDismiss={close} open={open}>Details</Popover>',
+  storyId: 'core-popover--default',
+} satisfies ComponentDoc;

package/src/Popover/Popover.tsx

@@ -0,0 +1,122 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useEffect,
+  useId,
+  type HTMLAttributes,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {
+  useAnchoredPosition,
+  type Alignment,
+  type Placement,
+} from '../hooks/useAnchoredPosition.js';
+import {Layer} from '../Layer/index.js';
+
+const styles = stylex.create({
+  surface: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationMedium,
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    padding: semanticTokens.spacingMd,
+    position: 'fixed',
+  },
+  hidden: {visibility: 'hidden'},
+});
+
+/** Props for a surface anchored to a trigger element. */
+export interface PopoverProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly alignment?: Alignment;
+  readonly anchorRef: RefObject<HTMLElement | null>;
+  readonly children: ReactNode;
+  readonly offset?: number;
+  readonly onDismiss?: () => void;
+  readonly open: boolean;
+  readonly placement?: Placement;
+}
+
+/**
+ * Floats content beside an anchor. Dismissal is non-modal: Escape and a click
+ * outside both close it, but the page behind stays scrollable and reachable.
+ */
+export function Popover({
+  alignment,
+  anchorRef,
+  children,
+  id,
+  offset,
+  onDismiss,
+  open,
+  placement,
+  role = 'dialog',
+  style,
+  ...props
+}: PopoverProps) {
+  const generatedId = useId();
+  const surfaceId = id ?? generatedId;
+  const {position, surface, surfaceRef} = useAnchoredPosition(anchorRef, open, {
+    ...(alignment ? {alignment} : {}),
+    ...(offset === undefined ? {} : {offset}),
+    ...(placement ? {placement} : {}),
+  });
+
+  useEffect(() => {
+    if (!open || !onDismiss) {
+      return;
+    }
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === 'Escape') {
+        onDismiss?.();
+      }
+    }
+
+    function handlePointerDown(event: MouseEvent) {
+      const target = event.target as Node;
+      if (surface?.contains(target) || anchorRef.current?.contains(target)) {
+        return;
+      }
+      onDismiss?.();
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('mousedown', handlePointerDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('mousedown', handlePointerDown);
+    };
+  }, [anchorRef, onDismiss, open, surface]);
+
+  if (!open) {
+    return null;
+  }
+
+  return (
+    <Layer>
+      <div
+        {...props}
+        data-placement={position?.placement}
+        id={surfaceId}
+        ref={surfaceRef}
+        role={role}
+        {...stylex.props(
+          styles.surface,
+          position === undefined && styles.hidden,
+        )}
+        style={{...style, left: position?.left, top: position?.top}}
+      >
+        {children}
+      </div>
+    </Layer>
+  );
+}

package/src/Popover/index.ts

@@ -0,0 +1 @@
+export {Popover, type PopoverProps} from './Popover.js';

package/src/PowerSearch/PowerSearch.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const powerSearchDoc = {
+  name: 'PowerSearch',
+  description: 'Searches with the applied filters shown beside the query.',
+  props: [
+    {name: 'filters', description: 'Supplies the filters already applied.'},
+    {name: 'label', description: 'Names the search field.'},
+    {name: 'onFiltersChange', description: 'Receives the remaining filters.'},
+    {name: 'onSearch', description: 'Receives the submitted query.'},
+    {name: 'placeholder', description: 'Hints at what to search for.'},
+    {name: 'submitLabel', description: 'Names the submit control.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLFormElement> except children, className, onSubmit, and role',
+  ],
+  example:
+    '<PowerSearch label="Search releases" onSearch={run} filters={applied} />',
+  storyId: 'core-power-search--default',
+} satisfies ComponentDoc;