@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/MultiSelector/MultiSelector.tsx

@@ -0,0 +1,89 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Stack} from '../Stack/index.js';
+import {Token} from '../Token/index.js';
+import {Typeahead, type TypeaheadOption} from '../Typeahead/index.js';
+
+const styles = stylex.create({
+  chips: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: semanticTokens.spacingXs,
+    listStyleType: 'none',
+    marginBlock: 0,
+    paddingInlineStart: 0,
+  },
+});
+
+/** Props for choosing several options through a typeahead. */
+export interface MultiSelectorProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange'
+> {
+  readonly emptyMessage?: string;
+  readonly label: string;
+  readonly onValueChange: (values: readonly string[]) => void;
+  readonly options: readonly TypeaheadOption[];
+  readonly removeLabel?: (label: string) => string;
+  readonly value: readonly string[];
+}
+
+/**
+ * Chooses several options through a typeahead. Each choice becomes a removable
+ * chip with its own labelled button, so a keyboard reader can undo one pick
+ * without clearing the rest.
+ */
+export function MultiSelector({
+  emptyMessage,
+  label,
+  onValueChange,
+  options,
+  removeLabel = (chosen) => `Remove ${chosen}`,
+  value,
+  ...props
+}: MultiSelectorProps) {
+  const [query, setQuery] = useState('');
+
+  const chosen = options.filter((option) => value.includes(option.value));
+  const available = options.filter(
+    (option) =>
+      !value.includes(option.value) &&
+      option.label.toLowerCase().includes(query.toLowerCase()),
+  );
+
+  return (
+    <Stack {...props} gap="sm">
+      {chosen.length === 0 ? null : (
+        <ul {...stylex.props(styles.chips)}>
+          {chosen.map((option) => (
+            <li key={option.value}>
+              <Token
+                onRemove={() => {
+                  onValueChange(
+                    value.filter((entry) => entry !== option.value),
+                  );
+                }}
+                removeLabel={removeLabel(option.label)}
+              >
+                {option.label}
+              </Token>
+            </li>
+          ))}
+        </ul>
+      )}
+      <Typeahead
+        aria-label={label}
+        {...(emptyMessage === undefined ? {} : {emptyMessage})}
+        inputValue={query}
+        onInputValueChange={setQuery}
+        onSelect={(option) => {
+          onValueChange([...value, option.value]);
+          setQuery('');
+        }}
+        options={available}
+      />
+    </Stack>
+  );
+}

package/src/MultiSelector/index.ts

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

package/src/NavIcon/NavIcon.doc.ts

@@ -0,0 +1,10 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const navIconDoc = {
+  name: 'NavIcon',
+  description: 'Reserves a fixed square for a navigation glyph.',
+  props: [{name: 'children', description: 'Supplies the glyph to place.'}],
+  inheritedProps: ['None; NavIcon owns its decorative wrapper'],
+  example: '<NavIcon><Icon>{path}</Icon></NavIcon>',
+  storyId: 'core-nav-icon--default',
+} satisfies ComponentDoc;

package/src/NavIcon/NavIcon.tsx

@@ -0,0 +1,45 @@
+import * as stylex from '@stylexjs/stylex';
+import type {ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  slot: {
+    alignItems: 'center',
+    color: 'inherit',
+    display: 'inline-flex',
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyBody,
+    // The em basis an `Icon` sizes itself against, held at the label's own
+    // size rather than above it. A mark drawn larger than the word it marks
+    // competes with it, and there is one down the left edge of every row.
+    fontSize: semanticTokens.fontSizeMd,
+    // The box is a fixed square, one step above the glyph inside it. It has to
+    // be fixed: sized from the label's own `fontSizeMd` the gutter moved
+    // whenever the type did, and `NavItem` could not reserve a matching one
+    // for a row that carries no glyph.
+    height: semanticTokens.fontSizeLg,
+    justifyContent: 'center',
+    // One glyph, so it is set solid: tracking has nothing to open here.
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightHeading,
+    width: semanticTokens.fontSizeLg,
+  },
+});
+
+/** Props for the fixed icon slot inside navigation. */
+export interface NavIconProps {
+  readonly children: ReactNode;
+}
+
+/**
+ * Reserves one fixed square for a navigation glyph so labels stay aligned
+ * whether or not a given item carries an icon.
+ */
+export function NavIcon({children}: NavIconProps) {
+  return (
+    <span aria-hidden="true" {...stylex.props(styles.slot)}>
+      {children}
+    </span>
+  );
+}

package/src/NavIcon/index.ts

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

package/src/NavItem/NavItem.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const navItemDoc = {
+  name: 'NavItem',
+  description: 'Links to one destination and can mark it as current.',
+  props: [
+    {name: 'current', description: 'Marks the destination the reader is on.'},
+    {name: 'href', description: 'Sets the destination the item links to.'},
+    {name: 'leading', description: 'Places a glyph before the label.'},
+  ],
+  inheritedProps: [
+    'AnchorHTMLAttributes<HTMLAnchorElement> except aria-current, className, and href',
+  ],
+  example: '<NavItem current href="/releases">Releases</NavItem>',
+  storyId: 'core-nav-item--default',
+} satisfies ComponentDoc;

package/src/NavItem/NavItem.tsx

@@ -0,0 +1,146 @@
+import * as stylex from '@stylexjs/stylex';
+import type {AnchorHTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Link} from '../navigation/index.js';
+import {useNavMenuOrientation} from '../NavMenu/orientation.js';
+
+// Two hairlines wide: one weight above the rules that separate regions, so the
+// mark reads as a deliberate stroke rather than as another divider. Written as
+// a calc over the border token so a theme that draws heavier lines gets a
+// heavier mark with it.
+//
+// Seven components declare this same pair, and it cannot be shared: StyleX
+// statically evaluates every identifier a style refers to, and it cannot
+// follow one across a module boundary — `stylex.create` throws on the import.
+// A shared module works for a whole compiled style (see `../scrolling`), not
+// for a raw value another file's `stylex.create` reads.
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const hoverMarkHeight = '40%';
+
+const styles = stylex.create({
+  item: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    color: semanticTokens.colorTextSecondary,
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    gap: semanticTokens.spacingSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    // Asymmetric on purpose: the label is set in from the inline-start edge so
+    // the mark has an edge of its own to stand on, instead of touching the
+    // word it marks. The trailing side only has to clear a count or a chevron.
+    paddingInlineEnd: semanticTokens.spacingSm,
+    paddingInlineStart: semanticTokens.spacingMd,
+    position: 'relative',
+    textDecorationLine: 'none',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    // The mark. Selection is a bar at the inline-start edge, never a fill
+    // behind the row: a filled row competes with the content beside it.
+    '::before': {
+      content: '',
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      transitionDuration: `${semanticTokens.durationFast}, ${semanticTokens.durationModerate}`,
+      transitionProperty: 'background-color, height',
+      transitionTimingFunction: semanticTokens.easingStandard,
+      width: markWidth,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  interactive: {
+    '::before': {
+      backgroundColor: semanticTokens.borderStrong,
+      height: {default: 0, ':hover': hoverMarkHeight},
+    },
+    ':hover': {color: semanticTokens.colorText},
+  },
+  // The current row is claimed by ink alone — no bar, no added weight. A rail
+  // is a short column of short words: a stroke beside one of them reads as a
+  // second divider, and bolding it makes the one row the reader is already on
+  // the heaviest thing on the page. Ink against second-rank ink is enough to
+  // find, and it leaves the rail quiet. `aria-current` still carries the fact
+  // for anyone who cannot see the difference.
+  current: {color: semanticTokens.colorText},
+  // The icon gutter is reserved whether or not this row carries a glyph, so a
+  // menu mixing marked and unmarked rows keeps one text edge for both.
+  // `NavIcon` has promised exactly this in its own doc comment all along;
+  // nothing kept the promise, and two adjacent labels sat 22px apart.
+  gutter: {
+    blockSize: semanticTokens.fontSizeLg,
+    flexShrink: 0,
+    inlineSize: semanticTokens.fontSizeLg,
+  },
+  // Laid across, the mark moves to the block edge. A bar at the inline start
+  // of a row in a horizontal menu stands between that row and the one before
+  // it, so it reads as a divider rather than as a mark on either — and the
+  // row's own leading padding puts it nowhere near the word it marks.
+  interactiveAcross: {
+    '::before': {
+      height: markWidth,
+      insetBlockStart: 'auto',
+      insetBlockEnd: 0,
+      insetInline: semanticTokens.spacingSm,
+      transform: 'none',
+      transitionProperty: 'background-color, opacity',
+      width: 'auto',
+      opacity: {default: 0, ':hover': 1},
+    },
+  },
+});
+
+/** Props for one destination inside a navigation menu. */
+export interface NavItemProps extends Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  'aria-current' | 'className' | 'href'
+> {
+  readonly current?: boolean;
+  readonly href: string;
+  readonly leading?: ReactNode;
+}
+
+/**
+ * Links to one destination. `current` marks the reader's location with
+ * `aria-current="page"` as well as ink, so the location is not carried by
+ * colour alone.
+ */
+export function NavItem({
+  children,
+  current = false,
+  href,
+  leading,
+  ...props
+}: NavItemProps) {
+  const orientation = useNavMenuOrientation();
+
+  return (
+    <Link
+      {...props}
+      {...(current ? {'aria-current': 'page' as const} : {})}
+      href={href}
+      {...stylex.props(
+        styles.item,
+        current ? styles.current : styles.interactive,
+        current || orientation === 'vertical'
+          ? undefined
+          : styles.interactiveAcross,
+      )}
+    >
+      {leading ?? <span aria-hidden="true" {...stylex.props(styles.gutter)} />}
+      {children}
+    </Link>
+  );
+}

package/src/NavItem/index.ts

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

package/src/NavMenu/NavMenu.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const navMenuDoc = {
+  name: 'NavMenu',
+  description: 'Groups destinations into a named navigation landmark.',
+  props: [
+    {name: 'children', description: 'Supplies the destinations.'},
+    {
+      name: 'label',
+      description: 'Names the landmark for assistive technology.',
+    },
+    {name: 'orientation', description: 'Selects the axis the list runs along.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLElement> except children and className'],
+  example:
+    '<NavMenu label="Primary"><NavItem href="/">Home</NavItem></NavMenu>',
+  storyId: 'core-nav-menu--default',
+} satisfies ComponentDoc;

package/src/NavMenu/NavMenu.tsx

@@ -0,0 +1,68 @@
+import * as stylex from '@stylexjs/stylex';
+import {Children, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {
+  NavMenuOrientationProvider,
+  type NavMenuOrientation,
+} from './orientation.js';
+
+const styles = stylex.create({
+  list: {
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    listStyleType: 'none',
+    marginBlock: 0,
+    marginInline: 0,
+    paddingInlineStart: 0,
+  },
+  horizontal: {
+    alignItems: 'center',
+    columnGap: semanticTokens.spacingXs,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    rowGap: semanticTokens.spacingXs,
+  },
+  // Rows stretch so every selection mark starts at the same inline edge, and
+  // they tile one hairline apart: the mark, not a gutter, separates them.
+  vertical: {
+    alignItems: 'stretch',
+    flexDirection: 'column',
+    rowGap: semanticTokens.borderWidth,
+  },
+});
+
+/** Props for a named group of navigation destinations. */
+export interface NavMenuProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly orientation?: NavMenuOrientation;
+}
+
+/**
+ * Groups destinations into a named navigation landmark. Each child becomes a
+ * list item, so assistive technology can announce how many destinations exist.
+ */
+export function NavMenu({
+  children,
+  label,
+  orientation = 'vertical',
+  ...props
+}: NavMenuProps) {
+  return (
+    <nav {...props} aria-label={label}>
+      {/* Each item draws its own mark, and where that mark belongs is a fact
+          about the menu rather than about the item. */}
+      <NavMenuOrientationProvider value={orientation}>
+        <ul {...stylex.props(styles.list, styles[orientation])}>
+          {Children.map(children, (child, index) => (
+            <li key={index}>{child}</li>
+          ))}
+        </ul>
+      </NavMenuOrientationProvider>
+    </nav>
+  );
+}

package/src/NavMenu/index.ts

@@ -0,0 +1,4 @@
+export {NavMenu, type NavMenuProps} from './NavMenu.js';
+// The orientation lives beside the context that carries it, because `NavItem`
+// reads it without going through `NavMenu` itself.
+export {useNavMenuOrientation, type NavMenuOrientation} from './orientation.js';

package/src/NavMenu/orientation.ts

@@ -0,0 +1,20 @@
+import {createContext, useContext} from 'react';
+
+/** Axis a navigation menu lays its destinations along. */
+export type NavMenuOrientation = 'horizontal' | 'vertical';
+
+/**
+ * The axis a `NavItem` is being laid along.
+ *
+ * An item cannot see its siblings, and the mark it draws depends on them: down
+ * the inline edge it belongs beside the word, across the block edge it belongs
+ * beneath it. Vertical is the default because an item outside any menu is a
+ * row in a rail.
+ */
+const NavMenuOrientationContext = createContext<NavMenuOrientation>('vertical');
+
+export const NavMenuOrientationProvider = NavMenuOrientationContext.Provider;
+
+export function useNavMenuOrientation() {
+  return useContext(NavMenuOrientationContext);
+}

package/src/NumberInput/NumberInput.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const numberInputDoc = {
+  name: 'NumberInput',
+  description: 'Accepts a number and reports an empty field as undefined.',
+  props: [
+    {
+      name: 'defaultValue',
+      description: 'Sets the initial uncontrolled number.',
+    },
+    {
+      name: 'onValueChange',
+      description: 'Receives the parsed number or undefined.',
+    },
+    {name: 'value', description: 'Controls the current number.'},
+  ],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except children, className, defaultValue, onChange, type, and value',
+  ],
+  example: '<NumberInput onValueChange={setCount} value={count} />',
+  storyId: 'core-number-input--default',
+} satisfies ComponentDoc;