@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Tokenizer/Tokenizer.tsx

@@ -0,0 +1,168 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type HTMLAttributes, type KeyboardEvent} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFieldControl} from '../Field/index.js';
+import {Token} from '../Token/index.js';
+
+// Wide enough that a half-typed tag is still readable once tokens wrap.
+const draftWidth = `calc(${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  frame: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexWrap: 'wrap',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingXs,
+    minHeight: semanticTokens.sizeControlMd,
+    padding: semanticTokens.spacingXs,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    // The ring belongs to the well, not to the field inside it. On the field
+    // it sat 4px out — 2px of offset plus 2px of stroke — inside a well with
+    // 3px of padding, so the well clipped a quarter of its own focus ring.
+    ':focus-within': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {borderColor: semanticTokens.borderInteractive},
+  },
+  // A well that is wrong says so on its own edge, the way every other well in
+  // the system does. Without this a `Field` could mark this control invalid,
+  // print the message underneath it, and leave the control itself unmarked.
+  frameInvalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-within': {borderColor: semanticTokens.statusDangerText},
+    ':hover': {borderColor: semanticTokens.statusDangerText},
+  },
+  input: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorText,
+    flexGrow: 1,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    minWidth: draftWidth,
+    // No block padding of its own: the well already spends a step on each
+    // side, and a second one inside it made an empty Tokenizer 34px tall
+    // where every other control in the row is 28px.
+    paddingBlock: 0,
+    paddingInline: semanticTokens.spacingXs,
+    '::placeholder': {color: semanticTokens.colorTextMuted},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+});
+
+/** Props for free-text entry that turns into discrete tokens. */
+export interface TokenizerProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange'
+> {
+  readonly label: string;
+  readonly onValueChange: (values: readonly string[]) => void;
+  readonly required?: boolean;
+  readonly placeholder?: string;
+  readonly removeLabel?: (value: string) => string;
+  readonly value: readonly string[];
+}
+
+/**
+ * Turns typed text into discrete tokens on Enter or comma. Backspace on an
+ * empty field removes the last token, which is what a reader expects from
+ * every other tag field they have used.
+ */
+export function Tokenizer({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  id,
+  label,
+  onValueChange,
+  placeholder,
+  removeLabel = (value) => `Remove ${value}`,
+  required,
+  value,
+  ...props
+}: TokenizerProps) {
+  const field = useFieldControl();
+  const [draft, setDraft] = useState('');
+  // The same reading of the field contract every other well makes. This one
+  // took only the id and the description from it, so a `Field` marked required
+  // or invalid reached the message but never the control.
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const invalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function commit() {
+    const entry = draft.trim();
+    if (entry === '' || value.includes(entry)) {
+      setDraft('');
+      return;
+    }
+    onValueChange([...value, entry]);
+    setDraft('');
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (event.key === 'Enter' || event.key === ',') {
+      event.preventDefault();
+      commit();
+      return;
+    }
+    if (event.key === 'Backspace' && draft === '' && value.length > 0) {
+      onValueChange(value.slice(0, -1));
+    }
+  }
+
+  return (
+    <div
+      {...props}
+      {...stylex.props(styles.frame, invalid && styles.frameInvalid)}
+    >
+      {value.map((entry) => (
+        <Token
+          key={entry}
+          onRemove={() => {
+            onValueChange(value.filter((candidate) => candidate !== entry));
+          }}
+          removeLabel={removeLabel(entry)}
+        >
+          {entry}
+        </Token>
+      ))}
+      <input
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        aria-label={label}
+        id={field?.controlId ?? id}
+        onBlur={commit}
+        onChange={(event) => {
+          setDraft(event.currentTarget.value);
+        }}
+        onKeyDown={handleKeyDown}
+        placeholder={placeholder}
+        required={required ?? field?.required}
+        value={draft}
+        {...stylex.props(styles.input)}
+        type="text"
+      />
+    </div>
+  );
+}

package/src/Tokenizer/index.ts

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

package/src/Toolbar/Toolbar.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const toolbarDoc = {
+  name: 'Toolbar',
+  description: 'Groups related controls into a single tab stop.',
+  props: [
+    {name: 'children', description: 'Supplies the grouped controls.'},
+    {name: 'label', description: 'Names the toolbar for assistive technology.'},
+    {
+      name: 'orientation',
+      description: 'Selects the axis arrow keys travel along.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and role',
+  ],
+  example:
+    '<Toolbar label="Text style"><IconButton aria-label="Bold" /></Toolbar>',
+  storyId: 'core-toolbar--default',
+} satisfies ComponentDoc;

package/src/Toolbar/Toolbar.tsx

@@ -0,0 +1,74 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useListFocus} from '../hooks/useListFocus.js';
+import type {ListOrientation} from '../hooks/useListFocus.js';
+
+// Tools sit against each other, parted by the width of a rule rather than by
+// a gutter. Spread on the spacing scale they read as three separate buttons
+// that happen to be near each other; closed up they read as one instrument.
+const toolGap = `calc(2 * ${semanticTokens.borderWidth})`;
+
+const styles = stylex.create({
+  // The strip carries no ground of its own: the controls inside it are the
+  // only marks, so the toolbar reads as a row of tools rather than a bar.
+  toolbar: {
+    alignItems: 'center',
+    color: semanticTokens.colorText,
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    minWidth: 0,
+  },
+  horizontal: {
+    columnGap: toolGap,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    rowGap: toolGap,
+  },
+  vertical: {
+    alignItems: 'stretch',
+    flexDirection: 'column',
+    rowGap: toolGap,
+  },
+});
+
+/** Props for a grouped set of controls that shares one tab stop. */
+export interface ToolbarProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role'
+> {
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly orientation?: ListOrientation;
+}
+
+/**
+ * Groups related controls into one tab stop. Arrow keys move between the
+ * controls, so a toolbar of ten buttons does not cost ten Tab presses.
+ */
+export function Toolbar({
+  children,
+  label,
+  orientation = 'horizontal',
+  ...props
+}: ToolbarProps) {
+  const toolbarRef = useRef<HTMLDivElement>(null);
+  const {onKeyDown} = useListFocus(toolbarRef, {orientation});
+
+  return (
+    <div
+      {...props}
+      aria-label={label}
+      aria-orientation={orientation}
+      onKeyDown={onKeyDown}
+      ref={toolbarRef}
+      role="toolbar"
+      {...stylex.props(styles.toolbar, styles[orientation])}
+    >
+      {children}
+    </div>
+  );
+}

package/src/Toolbar/index.ts

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

package/src/Tooltip/Tooltip.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const tooltipDoc = {
+  name: 'Tooltip',
+  description: 'Describes its trigger on hover and on focus.',
+  props: [
+    {
+      name: 'alignment',
+      description: 'Lines the surface up along the cross axis.',
+    },
+    {name: 'children', description: 'Supplies the single trigger element.'},
+    {name: 'content', description: 'Supplies the supplementary description.'},
+    {name: 'delay', description: 'Sets the hover delay in milliseconds.'},
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the trigger.',
+    },
+  ],
+  inheritedProps: ['None; Tooltip renders only its trigger and description'],
+  example: '<Tooltip content="Saves a draft"><Button>Save</Button></Tooltip>',
+  storyId: 'core-tooltip--default',
+} satisfies ComponentDoc;

package/src/Tooltip/Tooltip.tsx

@@ -0,0 +1,166 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  Children,
+  cloneElement,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type FocusEvent,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {
+  useAnchoredPosition,
+  type Alignment,
+  type Placement,
+} from '../hooks/useAnchoredPosition.js';
+import {Layer} from '../Layer/index.js';
+
+// A tooltip stays narrow enough to read in one or two lines; the scale stops
+// at 38px, so the cap is a named multiple of it rather than a rem literal.
+const surfaceMaxWidth = `calc(${semanticTokens.spacing2xl} * 8)`;
+
+const styles = stylex.create({
+  surface: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationMedium,
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    maxWidth: surfaceMaxWidth,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    pointerEvents: 'none',
+    position: 'fixed',
+  },
+  hidden: {visibility: 'hidden'},
+});
+
+interface TriggerProps {
+  readonly 'aria-describedby'?: string;
+  readonly onBlur?: (event: FocusEvent<HTMLElement>) => void;
+  readonly onFocus?: (event: FocusEvent<HTMLElement>) => void;
+  readonly onMouseEnter?: (event: MouseEvent<HTMLElement>) => void;
+  readonly onMouseLeave?: (event: MouseEvent<HTMLElement>) => void;
+  readonly ref?: unknown;
+}
+
+/** Props for a hover- and focus-triggered description. */
+export interface TooltipProps {
+  readonly alignment?: Alignment;
+  readonly children: ReactElement<TriggerProps>;
+  readonly content: ReactNode;
+  readonly delay?: number;
+  readonly placement?: Placement;
+}
+
+/**
+ * Describes its trigger on hover and on focus. The description is wired with
+ * `aria-describedby`, so it supplements the trigger's name rather than
+ * replacing it — never put essential information here alone.
+ */
+export function Tooltip({
+  alignment,
+  children,
+  content,
+  delay = 300,
+  placement = 'top',
+}: TooltipProps) {
+  const anchorRef = useRef<HTMLElement>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const [open, setOpen] = useState(false);
+  const describedBy = useId();
+
+  const {position, surfaceRef} = useAnchoredPosition(anchorRef, open, {
+    ...(alignment ? {alignment} : {}),
+    placement,
+  });
+
+  useEffect(
+    () => () => {
+      clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === 'Escape') {
+        setOpen(false);
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [open]);
+
+  function show() {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      setOpen(true);
+    }, delay);
+  }
+
+  function hide() {
+    clearTimeout(timer.current);
+    setOpen(false);
+  }
+
+  const trigger = Children.only(children);
+  const anchor = cloneElement(trigger, {
+    'aria-describedby': open ? describedBy : trigger.props['aria-describedby'],
+    onBlur: (event: FocusEvent<HTMLElement>) => {
+      trigger.props.onBlur?.(event);
+      hide();
+    },
+    onFocus: (event: FocusEvent<HTMLElement>) => {
+      trigger.props.onFocus?.(event);
+      show();
+    },
+    onMouseEnter: (event: MouseEvent<HTMLElement>) => {
+      trigger.props.onMouseEnter?.(event);
+      show();
+    },
+    onMouseLeave: (event: MouseEvent<HTMLElement>) => {
+      trigger.props.onMouseLeave?.(event);
+      hide();
+    },
+    ref: anchorRef,
+  });
+
+  return (
+    <>
+      {anchor}
+      {open ? (
+        <Layer>
+          <div
+            data-placement={position?.placement}
+            id={describedBy}
+            ref={surfaceRef}
+            role="tooltip"
+            {...stylex.props(
+              styles.surface,
+              position === undefined && styles.hidden,
+            )}
+            style={{left: position?.left, top: position?.top}}
+          >
+            {content}
+          </div>
+        </Layer>
+      ) : null}
+    </>
+  );
+}

package/src/Tooltip/index.ts

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

package/src/TopNav/TopNav.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const topNavDoc = {
+  name: 'TopNav',
+  description: 'Places identity, navigation, and actions in the page banner.',
+  props: [
+    {
+      name: 'actions',
+      description: 'Places account or global actions at the end.',
+    },
+    {name: 'brand', description: 'Places identity at the start of the banner.'},
+    {name: 'children', description: 'Supplies the primary navigation.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLElement> except children, className, and role',
+  ],
+  example:
+    '<TopNav brand="Kioku"><NavMenu label="Primary">…</NavMenu></TopNav>',
+  storyId: 'core-top-nav--default',
+} satisfies ComponentDoc;

package/src/TopNav/TopNav.tsx

@@ -0,0 +1,80 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  // The masthead is the top of the same sheet the page is printed on, not a
+  // bar laid over it: the rule under it is the only thing that parts the two.
+  // Painting it `colorSurface` made the banner read as a card the width of the
+  // window, which put the shell on the same rung as the cards inside it.
+  bar: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorCanvas,
+    borderBlockEndColor: semanticTokens.borderDefault,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    columnGap: semanticTokens.spacingLg,
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    // One hit target tall, so the banner keeps its height whether it holds a
+    // wordmark alone or a wordmark, a menu, and a row of account tools.
+    minHeight: semanticTokens.sizeHitTarget,
+    paddingBlock: semanticTokens.spacingSm,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  // A wordmark, so it is cut in the display face and tracked as a display
+  // name rather than as a heading. It carries the medium weight the rest of
+  // the masthead does: a bolder wordmark shouts across a bar that is otherwise
+  // all second-rank ink.
+  brand: {
+    alignItems: 'center',
+    color: semanticTokens.colorText,
+    columnGap: semanticTokens.spacingSm,
+    display: 'flex',
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeLg,
+    fontSynthesis: 'none',
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightHeading,
+  },
+  navigation: {flexGrow: 1, minWidth: 0},
+  actions: {
+    alignItems: 'center',
+    columnGap: semanticTokens.spacingSm,
+    display: 'flex',
+    flexShrink: 0,
+  },
+});
+
+/** Props for the banner across the top of an application. */
+export interface TopNavProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'className' | 'role'
+> {
+  readonly actions?: ReactNode;
+  readonly brand?: ReactNode;
+  readonly children?: ReactNode;
+}
+
+/**
+ * Places identity, primary navigation, and account actions in one banner.
+ * It emits `header`, so it is the page banner landmark.
+ */
+export function TopNav({actions, brand, children, ...props}: TopNavProps) {
+  return (
+    <header {...props} {...stylex.props(styles.bar)}>
+      {brand === undefined ? null : (
+        <div {...stylex.props(styles.brand)}>{brand}</div>
+      )}
+      {children === undefined ? null : (
+        <div {...stylex.props(styles.navigation)}>{children}</div>
+      )}
+      {actions === undefined ? null : (
+        <div {...stylex.props(styles.actions)}>{actions}</div>
+      )}
+    </header>
+  );
+}

package/src/TopNav/index.ts

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

package/src/TopNavMegaMenu/TopNavMegaMenu.doc.ts

@@ -0,0 +1,36 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const topNavMegaMenuDoc = {
+  name: 'TopNavMegaMenu',
+  description: 'A wide banner panel holding columns of destinations.',
+  props: [
+    {name: 'columns', description: 'Supplies the titled columns of links.'},
+    {
+      name: 'featured',
+      description: 'Places a promoted entry beside the columns.',
+    },
+    {name: 'label', description: 'Names the trigger and the panel.'},
+  ],
+  inheritedProps: ['None; TopNavMegaMenu owns its trigger and panel'],
+  example: '<TopNavMegaMenu columns={columns} label="Product" />',
+  storyId: 'core-top-nav-mega-menu--default',
+} satisfies ComponentDoc;
+
+export const topNavMegaMenuFeaturedCardDoc = {
+  name: 'TopNavMegaMenuFeaturedCard',
+  description: 'The promoted destination inside a mega menu.',
+  props: [
+    {
+      name: 'description',
+      description: 'Adds a supporting line under the title.',
+    },
+    {name: 'href', description: 'Sets the destination the card links to.'},
+    {name: 'media', description: 'Places an image or glyph above the title.'},
+    {name: 'title', description: 'Names the promoted destination.'},
+  ],
+  inheritedProps: [
+    'AnchorHTMLAttributes<HTMLAnchorElement> except children, className, href, media, and title',
+  ],
+  example: '<TopNavMegaMenuFeaturedCard href="/new" title="What’s new" />',
+  storyId: 'core-top-nav-mega-menu--default',
+} satisfies ComponentDoc;