@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/TreeList/TreeList.tsx

@@ -0,0 +1,265 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {reachableElements} from '../hooks/focusableSelector.js';
+import {Icon} from '../Icon/index.js';
+
+// A selected row is marked by a 2px accent bar against its leading edge, not
+// by a fill. `focusWidth` is this system's 2px.
+const selectionMark = `inset ${semanticTokens.focusWidth} 0 0 0 ${semanticTokens.colorAccent}`;
+
+// The disclosure column, and where the rule beneath it falls. Both are
+// relationships rather than sizes: the marker occupies three spacing steps, the
+// rule drops through the middle of that column, and the row's own inline
+// padding shifts both. A density change moves the marker and its rule together.
+const markerColumn = `calc(3 * ${semanticTokens.spacingSm})`;
+const markerCentre = `calc(1.5 * ${semanticTokens.spacingSm})`;
+const guideIndent = `calc(${semanticTokens.spacingSm} + ${markerCentre})`;
+
+const styles = stylex.create({
+  tree: {
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    listStyleType: 'none',
+    marginBlock: 0,
+    paddingInlineStart: 0,
+  },
+  // Children hang from one rule dropped through the marker that opened them,
+  // so depth is read off a single continuous stroke rather than off the left
+  // edge of every row. The inline margin is that indent — not sibling spacing,
+  // which the rows' own padding supplies.
+  group: {
+    borderInlineStartColor: semanticTokens.borderDefault,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexDirection: 'column',
+    listStyleType: 'none',
+    marginBlock: 0,
+    marginInlineStart: guideIndent,
+    paddingInlineStart: 0,
+  },
+  node: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    fontWeight: semanticTokens.fontWeightRegular,
+    gap: semanticTokens.spacingXs,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    // A ledger line, not a menu row. The rows are set close enough that the
+    // indent rule reads as one stroke through them; the leading is what keeps
+    // them apart, so the padding only has to clear the type.
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    textAlign: 'start',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, box-shadow, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  unselected: {
+    boxShadow: 'none',
+    ':hover:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  // No weight change. This is a list a reader moves through with the arrow
+  // keys, and the label is proportional type: a heavier row is a WIDER row, so
+  // every press reflowed the line under the cursor. `NavItem` settled the same
+  // question the same way — ink alone is enough to find, and it leaves the
+  // column still. Weight remains a legal mark elsewhere (design-language §5);
+  // it is this case, a moving cursor over proportional text, that it fails.
+  selected: {
+    boxShadow: selectionMark,
+    color: semanticTokens.colorText,
+  },
+  // The marker holds its column whether or not the row has one, so every label
+  // in the tree starts on the same stem. Its ink is the third rank: it is
+  // apparatus, and it must not compete with the row it belongs to — including
+  // on the selected row, where the label alone is promoted.
+  marker: {
+    alignItems: 'center',
+    color: semanticTokens.colorTextMuted,
+    display: 'inline-flex',
+    flexShrink: 0,
+    justifyContent: 'center',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'transform',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: markerColumn,
+  },
+  markerOpen: {transform: 'rotate(90deg)'},
+});
+
+/** One node in a `TreeList`. */
+export interface TreeNode {
+  readonly children?: readonly TreeNode[];
+  readonly id: string;
+  readonly label: ReactNode;
+}
+
+/** Props for a collapsible hierarchy. */
+export interface TreeListProps extends Omit<
+  HTMLAttributes<HTMLUListElement>,
+  'aria-label' | 'children' | 'className' | 'onSelect' | 'role'
+> {
+  readonly expandedIds: readonly string[];
+  readonly label: string;
+  readonly nodes: readonly TreeNode[];
+  readonly onExpandedChange: (ids: readonly string[]) => void;
+  readonly onSelect?: (id: string) => void;
+  readonly selectedId?: string;
+}
+
+/**
+ * Presents a collapsible hierarchy. The whole tree is one tab stop: up and
+ * down move between visible nodes, right opens a branch, left closes it.
+ */
+export function TreeList({
+  expandedIds,
+  label,
+  nodes,
+  onExpandedChange,
+  onSelect,
+  selectedId,
+  ...props
+}: TreeListProps) {
+  const treeRef = useRef<HTMLUListElement>(null);
+  const [focusedId, setFocusedId] = useState(nodes[0]?.id ?? '');
+
+  function toggle(id: string, open: boolean) {
+    onExpandedChange(
+      open ? [...expandedIds, id] : expandedIds.filter((entry) => entry !== id),
+    );
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLUListElement>) {
+    const tree = treeRef.current;
+    if (!tree) {
+      return;
+    }
+
+    const items = reachableElements(tree);
+    const current = items.indexOf(document.activeElement as HTMLElement);
+
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      const step = event.key === 'ArrowDown' ? 1 : -1;
+      const next = items[(current + step + items.length) % items.length];
+      next?.focus({preventScroll: true});
+      return;
+    }
+
+    const active = items[current];
+    const id = active?.dataset['nodeId'];
+    if (id === undefined) {
+      return;
+    }
+
+    if (event.key === 'ArrowRight' && active?.dataset['branch'] === 'true') {
+      event.preventDefault();
+      toggle(id, true);
+      return;
+    }
+    if (event.key === 'ArrowLeft' && active?.dataset['branch'] === 'true') {
+      event.preventDefault();
+      toggle(id, false);
+    }
+  }
+
+  function renderNodes(entries: readonly TreeNode[], level: number) {
+    return entries.map((node) => {
+      const branch = (node.children?.length ?? 0) > 0;
+      const open = expandedIds.includes(node.id);
+
+      return (
+        <li key={node.id} role="none">
+          <button
+            aria-current={node.id === selectedId ? 'true' : undefined}
+            {...(branch ? {'aria-expanded': open} : {})}
+            aria-level={level}
+            aria-selected={node.id === selectedId}
+            data-branch={branch ? 'true' : 'false'}
+            data-node-id={node.id}
+            onClick={() => {
+              setFocusedId(node.id);
+              if (branch) {
+                toggle(node.id, !open);
+              }
+              onSelect?.(node.id);
+            }}
+            role="treeitem"
+            {...stylex.props(
+              styles.node,
+              node.id === selectedId ? styles.selected : styles.unselected,
+            )}
+            tabIndex={node.id === focusedId ? 0 : -1}
+            type="button"
+          >
+            <span
+              aria-hidden="true"
+              {...stylex.props(
+                styles.marker,
+                branch && open && styles.markerOpen,
+              )}
+            >
+              {branch ? (
+                <Icon>
+                  <path
+                    d="m9 6 6 6-6 6"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                  />
+                </Icon>
+              ) : null}
+            </span>
+            {node.label}
+          </button>
+          {branch && open ? (
+            <ul role="group" {...stylex.props(styles.group)}>
+              {renderNodes(node.children ?? [], level + 1)}
+            </ul>
+          ) : null}
+        </li>
+      );
+    });
+  }
+
+  return (
+    <ul
+      {...props}
+      aria-label={label}
+      onKeyDown={handleKeyDown}
+      ref={treeRef}
+      role="tree"
+      {...stylex.props(styles.tree)}
+    >
+      {renderNodes(nodes, 1)}
+    </ul>
+  );
+}

package/src/TreeList/index.ts

@@ -0,0 +1 @@
+export {TreeList, type TreeListProps, type TreeNode} from './TreeList.js';

package/src/Typeahead/Typeahead.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const typeaheadDoc = {
+  name: 'Typeahead',
+  description: 'Filters suggestions as the reader types.',
+  props: [
+    {name: 'emptyMessage', description: 'States that nothing matched.'},
+    {name: 'inputValue', description: 'Controls the text in the field.'},
+    {name: 'onInputValueChange', description: 'Receives the typed text.'},
+    {name: 'onSelect', description: 'Receives the chosen suggestion.'},
+    {
+      name: 'options',
+      description: 'Supplies the suggestions already filtered.',
+    },
+  ],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except children, className, onChange, onKeyDown, onSelect, role, type, value, autoComplete, and the combobox aria attributes',
+  ],
+  example:
+    '<Typeahead inputValue={query} onInputValueChange={setQuery} onSelect={choose} options={matches} />',
+  storyId: 'core-typeahead--default',
+} satisfies ComponentDoc;

package/src/Typeahead/Typeahead.tsx

@@ -0,0 +1,312 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useId,
+  useState,
+  type InputHTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {useInternationalization} from '../i18n/index.js';
+import {useFieldControl} from '../Field/index.js';
+
+// The popup hangs one hairline gap below the field it belongs to.
+const listboxOffset = `calc(100% + ${semanticTokens.spacingXs})`;
+// Roughly eight rows before the list starts scrolling.
+const listboxHeight = `calc(8 * ${semanticTokens.spacing2xl})`;
+
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const markHeight = '64%';
+
+const styles = stylex.create({
+  root: {display: 'grid', position: 'relative'},
+  // A field sinks: the muted fill and the strong edge are what every other
+  // text control in the system is painted with. Surface plus a hairline is
+  // the read-only treatment, and wearing it at rest flattened the ladder.
+  input: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    height: semanticTokens.sizeControlMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    '::placeholder': {color: semanticTokens.colorTextMuted},
+    ':disabled': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      borderColor: semanticTokens.borderDisabled,
+      color: semanticTokens.colorDisabledText,
+    },
+    ':focus-visible': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.borderInteractive,
+    },
+  },
+  readOnly: {
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
+    color: semanticTokens.colorText,
+  },
+  invalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-visible': {borderColor: semanticTokens.statusDangerText},
+    ':hover:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.statusDangerText,
+    },
+  },
+  panel: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationMedium,
+    insetBlockStart: listboxOffset,
+    insetInline: 0,
+    maxHeight: listboxHeight,
+    overflowY: 'auto',
+    paddingBlock: semanticTokens.spacingXs,
+    position: 'absolute',
+    zIndex: 1,
+  },
+  listbox: {listStyleType: 'none', marginBlock: 0, paddingInlineStart: 0},
+  // A suggestion that is merely on offer is set in the second rank; the one
+  // the keys are pointing at rises to the first.
+  option: {
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingMd,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  idle: {
+    ':hover': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  // The combobox keeps focus, so the row it points at has to say so on its
+  // own: the wash, the first rank of ink, and the bookmark at the inline-start
+  // edge — the same mark the sidebar uses, never a filled bar.
+  // No weight change. This is a list a reader moves through with the arrow
+  // keys, and the label is proportional type: a heavier row is a WIDER row, so
+  // every press reflowed the line under the cursor. `NavItem` settled the same
+  // question the same way — ink alone is enough to find, and it leaves the
+  // column still. Weight remains a legal mark elsewhere (design-language §5);
+  // it is this case, a moving cursor over proportional text, that it fails.
+  active: {
+    backgroundColor: semanticTokens.colorOverlayHover,
+    color: semanticTokens.colorText,
+    '::before': {
+      backgroundColor: semanticTokens.colorAccent,
+      content: '',
+      height: markHeight,
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      width: markWidth,
+    },
+  },
+  empty: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    marginBlock: 0,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingMd,
+  },
+});
+
+/** One suggestion offered by a `Typeahead`. */
+export interface TypeaheadOption {
+  readonly label: string;
+  readonly value: string;
+}
+
+/** Props for a text field with filtered suggestions. */
+export interface TypeaheadProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  | 'aria-activedescendant'
+  | 'aria-autocomplete'
+  | 'aria-controls'
+  | 'aria-expanded'
+  | 'autoComplete'
+  | 'children'
+  | 'className'
+  | 'onChange'
+  | 'onKeyDown'
+  | 'onSelect'
+  | 'role'
+  | 'type'
+  | 'value'
+> {
+  readonly emptyMessage?: ReactNode;
+  readonly inputValue: string;
+  readonly onInputValueChange: (value: string) => void;
+  readonly onSelect: (option: TypeaheadOption) => void;
+  readonly options: readonly TypeaheadOption[];
+}
+
+/**
+ * Filters suggestions as the reader types, following the ARIA combobox
+ * pattern: the input keeps focus and `aria-activedescendant` names the
+ * highlighted option, so a screen reader announces it without focus moving.
+ */
+export function Typeahead({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  disabled,
+  emptyMessage,
+  id,
+  inputValue,
+  onInputValueChange,
+  onSelect,
+  options,
+  readOnly,
+  required,
+  ...props
+}: TypeaheadProps) {
+  const field = useFieldControl();
+  const {messages} = useInternationalization();
+  const listboxId = useId();
+  const optionPrefix = useId();
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  const expanded = open && inputValue !== '';
+  const activeOption = options[activeIndex];
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const isInvalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      setOpen(true);
+      if (options.length > 0) {
+        const step = event.key === 'ArrowDown' ? 1 : -1;
+        setActiveIndex(
+          (index) => (index + step + options.length) % options.length,
+        );
+      }
+      return;
+    }
+    if (event.key === 'Home' || event.key === 'End') {
+      if (!expanded || options.length === 0) {
+        return;
+      }
+      event.preventDefault();
+      setActiveIndex(event.key === 'Home' ? 0 : options.length - 1);
+      return;
+    }
+    if (event.key === 'Enter' && expanded && activeOption) {
+      event.preventDefault();
+      onSelect(activeOption);
+      setOpen(false);
+      return;
+    }
+    if (event.key === 'Escape') {
+      setOpen(false);
+    }
+  }
+
+  return (
+    <div {...stylex.props(styles.root)}>
+      <input
+        {...props}
+        aria-activedescendant={
+          expanded && activeOption
+            ? `${optionPrefix}-${activeIndex}`
+            : undefined
+        }
+        aria-autocomplete="list"
+        // Named only while the popup it points at is rendered.
+        aria-controls={expanded ? listboxId : undefined}
+        aria-describedby={describedBy}
+        aria-expanded={expanded}
+        aria-invalid={resolvedInvalid}
+        autoComplete="off"
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        onChange={(event) => {
+          onInputValueChange(event.currentTarget.value);
+          setActiveIndex(0);
+          setOpen(true);
+        }}
+        onKeyDown={handleKeyDown}
+        readOnly={readOnly}
+        required={required ?? field?.required}
+        role="combobox"
+        value={inputValue}
+        {...stylex.props(
+          styles.input,
+          readOnly && !disabled ? styles.readOnly : undefined,
+          isInvalid && !disabled ? styles.invalid : undefined,
+        )}
+        type="text"
+      />
+      {!expanded ? null : (
+        <div {...stylex.props(styles.panel, scrolling.region)}>
+          <ul id={listboxId} role="listbox" {...stylex.props(styles.listbox)}>
+            {options.map((option, index) => (
+              <li
+                aria-selected={index === activeIndex}
+                id={`${optionPrefix}-${index}`}
+                key={option.value}
+                onClick={() => {
+                  onSelect(option);
+                  setOpen(false);
+                }}
+                role="option"
+                {...stylex.props(
+                  styles.option,
+                  index === activeIndex ? styles.active : styles.idle,
+                )}
+              >
+                {option.label}
+              </li>
+            ))}
+          </ul>
+          {options.length === 0 ? (
+            // A listbox may own nothing but options, so the notice sits beside
+            // it and announces itself instead.
+            <p role="status" {...stylex.props(styles.empty)}>
+              {emptyMessage ?? messages.typeaheadEmpty}
+            </p>
+          ) : null}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/Typeahead/index.ts

@@ -0,0 +1,5 @@
+export {
+  Typeahead,
+  type TypeaheadOption,
+  type TypeaheadProps,
+} from './Typeahead.js';

package/src/TypeaheadItem/TypeaheadItem.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const typeaheadItemDoc = {
+  name: 'TypeaheadItem',
+  description: 'One suggestion inside a typeahead listbox.',
+  props: [
+    {name: 'active', description: 'Marks the option the combobox points at.'},
+    {name: 'description', description: 'Adds secondary text under the label.'},
+    {name: 'disabled', description: 'Marks the option as unavailable.'},
+    {name: 'leading', description: 'Places content before the label.'},
+    {name: 'trailing', description: 'Places content after the label.'},
+  ],
+  inheritedProps: [
+    'LiHTMLAttributes<HTMLLIElement> except aria-disabled, aria-selected, className, and role',
+  ],
+  example: '<TypeaheadItem active>Ada Lovelace</TypeaheadItem>',
+  storyId: 'core-typeahead--states',
+} satisfies ComponentDoc;