@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/NumberInput/NumberInput.tsx

@@ -0,0 +1,286 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useRef,
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFieldControl} from '../Field/index.js';
+
+const styles = stylex.create({
+  // An input sinks below the card it sits on: a muted fill with a real
+  // hairline edge, never a shadow. The figures are monospaced and tabular —
+  // this field is usually one of a stacked column of them, and proportional
+  // digits put every value on its own margin. Mono is also the one type role
+  // that tightens rather than opens.
+  // The well is the frame now, because something else lives inside it. Left as
+  // one bare `<input type="number">`, this control drew a careful well and then
+  // let Chrome grow a pair of grey arrows in the corner of it — the one part of
+  // the field the component had no say over.
+  frame: {
+    alignItems: 'stretch',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    display: 'flex',
+    height: semanticTokens.sizeControlMd,
+    overflow: 'hidden',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':focus-within': {borderColor: semanticTokens.borderInteractive},
+    ':hover': {borderColor: semanticTokens.borderInteractive},
+  },
+  frameDisabled: {
+    backgroundColor: semanticTokens.colorDisabledSurface,
+    borderColor: semanticTokens.borderDisabled,
+    ':hover': {borderColor: semanticTokens.borderDisabled},
+  },
+  frameReadOnly: {
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
+  },
+  frameInvalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-within': {borderColor: semanticTokens.statusDangerText},
+    ':hover': {borderColor: semanticTokens.statusDangerText},
+  },
+  // The steppers are a column inside the well, parted from the figure by the
+  // same hairline that parts anything from anything here — not a pair of
+  // buttons floating on top of it.
+  steppers: {
+    borderInlineStartColor: semanticTokens.borderDefault,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexDirection: 'column',
+    flexShrink: 0,
+    inlineSize: semanticTokens.spacingXl,
+  },
+  // Pointer affordances only: `aria-hidden` and out of the tab order, because
+  // the input already steps on the arrow keys and a screen reader already
+  // hears a spinbutton. Two more tab stops per field would be two more than
+  // the control needs.
+  step: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    cursor: 'pointer',
+    display: 'flex',
+    flexGrow: 1,
+    justifyContent: 'center',
+    padding: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':hover': {backgroundColor: semanticTokens.colorOverlayHover},
+    ':active': {backgroundColor: semanticTokens.colorOverlayActive},
+    // The chevron: two edges of an empty square stood on a corner, the same
+    // way the checkbox draws its tick. It takes its colour from the palette,
+    // which is the whole point of not letting the engine draw it.
+    '::before': {
+      blockSize: semanticTokens.spacingSm,
+      borderBlockStartColor: semanticTokens.colorTextSecondary,
+      borderBlockStartStyle: semanticTokens.borderStyle,
+      borderBlockStartWidth: semanticTokens.borderWidth,
+      borderInlineStartColor: semanticTokens.colorTextSecondary,
+      borderInlineStartStyle: semanticTokens.borderStyle,
+      borderInlineStartWidth: semanticTokens.borderWidth,
+      content: '',
+      inlineSize: semanticTokens.spacingSm,
+      position: 'absolute',
+    },
+  },
+  stepUp: {
+    borderBlockEndColor: semanticTokens.borderDefault,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    '::before': {transform: 'translateY(25%) rotate(45deg)'},
+  },
+  stepDown: {
+    '::before': {transform: 'translateY(-25%) rotate(225deg)'},
+  },
+  control: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeMd,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+    minWidth: 0,
+    // Firefox and Blink each grow their own stepper in the corner of a number
+    // field. Neither can be styled into this system, and the component draws
+    // its own beside them, so both are turned off rather than tinted.
+    MozAppearance: 'textfield',
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    textAlign: 'end',
+    width: '100%',
+    '::-webkit-inner-spin-button': {appearance: 'none', margin: 0},
+    '::-webkit-outer-spin-button': {appearance: 'none', margin: 0},
+    '::placeholder': {color: semanticTokens.colorTextMuted},
+    ':disabled': {color: semanticTokens.colorDisabledText},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+  // Read-only is not disabled: the figure still reads at full strength, but
+  // the control stops looking like a well you can type into — and it loses
+  // the steppers, because there is nothing to step.
+  readOnly: {color: semanticTokens.colorText},
+});
+
+type SharedNumberInputProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange' | 'type' | 'value'
+> & {
+  readonly onValueChange?: (value: number | undefined) => void;
+};
+
+type ControlledNumberInputProps = SharedNumberInputProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: number | undefined) => void;
+  readonly value: number | undefined;
+};
+
+type UncontrolledNumberInputProps = SharedNumberInputProps & {
+  readonly defaultValue?: number;
+  readonly value?: never;
+};
+
+/** Props for a numeric entry field. */
+export type NumberInputProps =
+  ControlledNumberInputProps | UncontrolledNumberInputProps;
+
+/**
+ * Accepts a number. An empty field reports `undefined` rather than `0`, so a
+ * caller can tell "not answered" apart from "answered zero".
+ */
+export function NumberInput(props: NumberInputProps) {
+  // `value` may legitimately be undefined while controlled, so presence of the
+  // prop — not its value — decides which mode the field is in.
+  const controlled = 'value' in props;
+  const {
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    defaultValue,
+    disabled,
+    id,
+    onValueChange,
+    readOnly,
+    required,
+    value,
+    ...rest
+  } = props;
+
+  const field = useFieldControl();
+  const controlRef = useRef<HTMLInputElement>(null);
+  const [internalValue, setInternalValue] = useState(
+    defaultValue === undefined ? '' : String(defaultValue),
+  );
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const invalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function report(raw: string) {
+    if (!controlled) {
+      setInternalValue(raw);
+    }
+    onValueChange?.(raw === '' ? undefined : Number(raw));
+  }
+
+  function handleChange(event: ChangeEvent<HTMLInputElement>) {
+    report(event.currentTarget.value);
+  }
+
+  // The step is taken by the input itself: `stepUp`/`stepDown` already honour
+  // `step`, `min` and `max`, and re-implementing that arithmetic here would be
+  // a second, worse copy of a rule the platform already keeps.
+  function step(direction: 'down' | 'up') {
+    const control = controlRef.current;
+    if (!control) {
+      return;
+    }
+    if (direction === 'up') {
+      control.stepUp();
+    } else {
+      control.stepDown();
+    }
+    report(control.value);
+  }
+
+  const steppable = !disabled && !readOnly;
+
+  return (
+    <span
+      {...stylex.props(
+        styles.frame,
+        readOnly && !disabled ? styles.frameReadOnly : undefined,
+        invalid && !disabled ? styles.frameInvalid : undefined,
+        disabled ? styles.frameDisabled : undefined,
+      )}
+    >
+      <input
+        {...rest}
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        inputMode="decimal"
+        onChange={handleChange}
+        readOnly={readOnly}
+        ref={controlRef}
+        required={required ?? field?.required}
+        {...stylex.props(
+          styles.control,
+          readOnly && !disabled ? styles.readOnly : undefined,
+        )}
+        type="number"
+        value={
+          controlled
+            ? value === undefined
+              ? ''
+              : String(value)
+            : internalValue
+        }
+      />
+      {steppable ? (
+        <span {...stylex.props(styles.steppers)}>
+          <button
+            aria-hidden="true"
+            onClick={() => {
+              step('up');
+            }}
+            tabIndex={-1}
+            type="button"
+            {...stylex.props(styles.step, styles.stepUp)}
+          />
+          <button
+            aria-hidden="true"
+            onClick={() => {
+              step('down');
+            }}
+            tabIndex={-1}
+            type="button"
+            {...stylex.props(styles.step, styles.stepDown)}
+          />
+        </span>
+      ) : null}
+    </span>
+  );
+}

package/src/NumberInput/index.ts

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

package/src/Numeral/Numeral.doc.ts

@@ -0,0 +1,10 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const numeralDoc = {
+  name: 'Numeral',
+  description: 'Sets a figure in the mono face with tabular numerals.',
+  props: [{name: 'children', description: 'Supplies the figure.'}],
+  inheritedProps: ['HTMLAttributes<HTMLSpanElement> except className'],
+  example: '<Numeral>1,204</Numeral>',
+  storyId: 'core-numeral--default',
+} satisfies ComponentDoc;

package/src/Numeral/Numeral.tsx

@@ -0,0 +1,34 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  // Rule 44's figure, and nothing else. No size and no colour: `Code` keeps a
+  // ratio size for the same reason — "a ratio, not a size: inline code tracks
+  // whatever it is set inside". A figure inside a 30px metric is 30px and the
+  // same figure in a 12.5px table row is 12.5px, so the scale and the ink
+  // stay with whatever the figure is set inside; only the face changes.
+  base: {
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+  },
+});
+
+/** Props for a figure set in the mono face. */
+export type NumeralProps = Omit<HTMLAttributes<HTMLSpanElement>, 'className'>;
+
+/**
+ * Sets a figure — a count, a metric, a duration, a page number — in the mono
+ * face with tabular numerals, so a column of them lines up on the same stems.
+ * Named `Numeral` rather than `Figure` because `figure` already means an
+ * image with a caption in HTML.
+ */
+export function Numeral({children, ...props}: NumeralProps) {
+  return (
+    <span {...props} {...stylex.props(styles.base)}>
+      {children}
+    </span>
+  );
+}

package/src/Numeral/index.ts

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

package/src/Outline/Outline.doc.ts

@@ -0,0 +1,14 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const outlineDoc = {
+  name: 'Outline',
+  description: 'Lists the headings of the current page for in-page jumps.',
+  props: [
+    {name: 'currentHref', description: 'Marks which heading the reader is at.'},
+    {name: 'entries', description: 'Supplies the headings in reading order.'},
+    {name: 'label', description: 'Names the navigation landmark.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLElement> except children and className'],
+  example: '<Outline currentHref="#tokens" entries={headings} />',
+  storyId: 'core-outline--default',
+} satisfies ComponentDoc;

package/src/Outline/Outline.tsx

@@ -0,0 +1,124 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Link} from '../navigation/index.js';
+
+const styles = stylex.create({
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    // A hairline apart, so a run of entries reads as one ruled column rather
+    // than as separate rows — `SideNav` and `NavMenu` tile theirs the same
+    // way. At a full spacing step the rules beside each entry stopped being a
+    // continuous edge and became a dashed one.
+    gap: semanticTokens.borderWidth,
+    listStyleType: 'none',
+    marginBlock: 0,
+    paddingInlineStart: 0,
+  },
+  entry: {
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.focusWidth,
+    display: 'block',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    textDecorationLine: 'none',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  // Where the reader is, is a mark at the edge and a change of ink — never a
+  // filled row. Hover lives only on the entries that are not the mark.
+  inactive: {
+    borderInlineStartColor: semanticTokens.borderDefault,
+    color: semanticTokens.colorTextSecondary,
+    fontWeight: semanticTokens.fontWeightRegular,
+    ':hover': {
+      borderInlineStartColor: semanticTokens.borderStrong,
+      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.
+  current: {
+    borderInlineStartColor: semanticTokens.colorAccent,
+    color: semanticTokens.colorText,
+  },
+  depth1: {paddingInlineStart: semanticTokens.spacingMd},
+  depth2: {paddingInlineStart: semanticTokens.spacingXl},
+  depth3: {paddingInlineStart: semanticTokens.spacing2xl},
+});
+
+const depths = {
+  1: styles.depth1,
+  2: styles.depth2,
+  3: styles.depth3,
+} as const;
+
+/** One heading in the page outline. */
+export interface OutlineEntry {
+  readonly depth?: 1 | 2 | 3;
+  readonly href: string;
+  readonly label: ReactNode;
+}
+
+/** Props for the in-page table of contents. */
+export interface OutlineProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'className'
+> {
+  readonly currentHref?: string;
+  readonly entries: readonly OutlineEntry[];
+  readonly label?: string;
+}
+
+/**
+ * Lists the headings of the current page so a reader can jump between them.
+ * The active entry is marked with `aria-current`, not colour alone.
+ */
+export function Outline({
+  currentHref,
+  entries,
+  label = 'On this page',
+  ...props
+}: OutlineProps) {
+  return (
+    <nav {...props} aria-label={label}>
+      <ul {...stylex.props(styles.list)}>
+        {entries.map(({depth = 1, href, label: entryLabel}) => {
+          const current = href === currentHref;
+
+          return (
+            <li key={href}>
+              <Link
+                {...(current ? {'aria-current': 'location' as const} : {})}
+                href={href}
+                {...stylex.props(
+                  styles.entry,
+                  depths[depth],
+                  current ? styles.current : styles.inactive,
+                )}
+              >
+                {entryLabel}
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

package/src/Outline/index.ts

@@ -0,0 +1 @@
+export {Outline, type OutlineEntry, type OutlineProps} from './Outline.js';

package/src/OverflowList/OverflowList.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const overflowListDoc = {
+  name: 'OverflowList',
+  description: 'Shows leading entries and folds the rest into a menu.',
+  props: [
+    {name: 'entries', description: 'Supplies every entry in priority order.'},
+    {
+      name: 'overflowLabel',
+      description: 'Names the overflow trigger and menu.',
+    },
+    {
+      name: 'visibleCount',
+      description: 'Sets how many entries stay in the row.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example: '<OverflowList entries={actions} visibleCount={3} />',
+  storyId: 'core-overflow-list--default',
+} satisfies ComponentDoc;

package/src/OverflowList/OverflowList.tsx

@@ -0,0 +1,115 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, useState, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Button} from '../Button/index.js';
+import {DropdownMenu, DropdownMenuItem} from '../DropdownMenu/index.js';
+
+const styles = stylex.create({
+  row: {
+    alignItems: 'center',
+    display: 'flex',
+    flexWrap: 'nowrap',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingXs,
+    minWidth: 0,
+  },
+  item: {flexShrink: 0},
+  anchor: {display: 'inline-flex'},
+  label: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+  },
+  // How many are folded away is a figure, so it is set as one: mono and
+  // tabular, so the button does not change width between 9 and 10.
+  count: {
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+  },
+});
+
+/** One entry that can move into the overflow menu. */
+export interface OverflowEntry {
+  readonly label: string;
+  readonly node: ReactNode;
+  readonly onSelect?: () => void;
+}
+
+/** Props for a row that folds its tail into a menu. */
+export interface OverflowListProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly entries: readonly OverflowEntry[];
+  readonly overflowLabel?: string;
+  readonly visibleCount: number;
+}
+
+/**
+ * Shows the first `visibleCount` entries and folds the rest into a menu. The
+ * count is supplied by the caller rather than measured here, so the component
+ * stays predictable and does not thrash on resize.
+ */
+export function OverflowList({
+  entries,
+  overflowLabel = 'More',
+  visibleCount,
+  ...props
+}: OverflowListProps) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [open, setOpen] = useState(false);
+
+  const shown = entries.slice(0, visibleCount);
+  const hidden = entries.slice(visibleCount);
+
+  return (
+    <div {...props} {...stylex.props(styles.row)}>
+      {shown.map((entry) => (
+        <span key={entry.label} {...stylex.props(styles.item)}>
+          {entry.node}
+        </span>
+      ))}
+      {hidden.length === 0 ? null : (
+        <span {...stylex.props(styles.item)}>
+          <span ref={anchorRef} {...stylex.props(styles.anchor)}>
+            <Button
+              onClick={() => {
+                setOpen((value) => !value);
+              }}
+              size="sm"
+              variant="ghost"
+            >
+              <span {...stylex.props(styles.label)}>
+                {overflowLabel} (
+                <span {...stylex.props(styles.count)}>{hidden.length}</span>)
+              </span>
+            </Button>
+          </span>
+          <DropdownMenu
+            anchorRef={anchorRef}
+            label={overflowLabel}
+            onDismiss={() => {
+              setOpen(false);
+            }}
+            open={open}
+          >
+            {hidden.map((entry) => (
+              <DropdownMenuItem
+                key={entry.label}
+                onClick={() => {
+                  entry.onSelect?.();
+                  setOpen(false);
+                }}
+              >
+                {entry.label}
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenu>
+        </span>
+      )}
+    </div>
+  );
+}

package/src/OverflowList/index.ts

@@ -0,0 +1,5 @@
+export {
+  OverflowList,
+  type OverflowEntry,
+  type OverflowListProps,
+} from './OverflowList.js';

package/src/Overlay/Overlay.doc.ts

@@ -0,0 +1,23 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const overlayDoc = {
+  name: 'Overlay',
+  description: 'Supplies scrim, dismissal, focus, and scroll behaviour.',
+  props: [
+    {name: 'children', description: 'Supplies the surface the overlay wraps.'},
+    {
+      name: 'dismissOnOutsideClick',
+      description: 'Allows a click on the scrim to dismiss the overlay.',
+    },
+    {name: 'lockScroll', description: 'Freezes document scrolling while open.'},
+    {name: 'onDismiss', description: 'Runs on Escape or an outside click.'},
+    {name: 'open', description: 'Controls whether the overlay renders.'},
+    {name: 'scrim', description: 'Draws a dimming layer behind the surface.'},
+    {name: 'trapFocus', description: 'Confines Tab to the wrapped surface.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example: '<Overlay onDismiss={close} open={open}><Card>...</Card></Overlay>',
+  storyId: 'core-overlay--default',
+} satisfies ComponentDoc;