@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Toggle/Toggle.tsx

@@ -3,67 +3,92 @@ import {useState, type ButtonHTMLAttributes} from 'react';
 
 import {semanticTokens} from '../authoring.stylex.js';
 
+// The console's switch, in tokens, and the same block `Switch` is cut from —
+// the two are one control wearing two names, so they may not drift apart. Its
+// proportions are relationships rather than measurements: a track one spacing
+// step tall, a knob inset by a hairline on each side, and a travel of exactly
+// the difference between the track's two dimensions. Nothing here is a
+// literal, so the control keeps its proportions when density moves it.
+const trackHeight = semanticTokens.spacingLg;
+const trackWidth = semanticTokens.sizeControlMd;
+const knobInset = `calc(${semanticTokens.borderWidth} * 2)`;
+const knobSize = `calc(${trackHeight} - ${knobInset} * 2)`;
+const knobTravel = `calc(${trackWidth} - ${trackHeight})`;
+
 const styles = stylex.create({
   base: {
     alignItems: 'center',
     backgroundColor: 'transparent',
     borderColor: 'transparent',
-    borderRadius: semanticTokens.radiusFull,
+    borderRadius: semanticTokens.radiusElement,
     borderStyle: semanticTokens.borderStyle,
     borderWidth: semanticTokens.borderWidth,
+    cursor: 'pointer',
     display: 'inline-flex',
     color: semanticTokens.colorText,
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
     gap: semanticTokens.spacingSm,
     justifyContent: 'center',
     minHeight: semanticTokens.sizeHitTarget,
     minWidth: semanticTokens.sizeHitTarget,
     paddingBlock: semanticTokens.spacingXs,
     paddingInline: semanticTokens.spacingXs,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
     ':active:not(:disabled)': {
       backgroundImage: `linear-gradient(${semanticTokens.colorOverlayActive}, ${semanticTokens.colorOverlayActive})`,
     },
-    ':disabled': {color: semanticTokens.colorDisabledText},
+    ':disabled': {color: semanticTokens.colorDisabledText, cursor: 'default'},
     ':focus-visible': {
       outlineColor: semanticTokens.colorFocus,
       outlineOffset: semanticTokens.focusOffset,
       outlineStyle: semanticTokens.borderStyle,
       outlineWidth: semanticTokens.focusWidth,
     },
-    ':hover:not(:disabled)': {
+    ':hover:not(:disabled):not(:active)': {
       backgroundImage: `linear-gradient(${semanticTokens.colorOverlayHover}, ${semanticTokens.colorOverlayHover})`,
     },
   },
+  // No border. The track is a solid block that changes colour, not a small
+  // input box with something inside it — an outlined 14px track reads as a
+  // field that failed to grow, which is what this was. The corner is the
+  // sheet's 3px; a pill beside a 3px input reads as imported.
   track: {
     alignItems: 'center',
-    backgroundColor: semanticTokens.colorSurfaceMuted,
-    borderColor: semanticTokens.borderDefault,
-    borderRadius: semanticTokens.radiusFull,
-    borderStyle: semanticTokens.borderStyle,
-    borderWidth: semanticTokens.borderWidth,
+    backgroundColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    boxSizing: 'border-box',
     display: 'inline-flex',
     flexShrink: 0,
-    height: semanticTokens.spacingLg,
+    height: trackHeight,
     justifyContent: 'flex-start',
-    width: semanticTokens.sizeControlLg,
-  },
-  trackOn: {
-    backgroundColor: semanticTokens.colorAccent,
-    borderColor: semanticTokens.colorAccent,
-    justifyContent: 'flex-end',
-  },
-  trackDisabled: {
-    backgroundColor: semanticTokens.colorDisabledSurface,
-    borderColor: semanticTokens.borderDisabled,
+    padding: knobInset,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: trackWidth,
   },
+  // On is ink. "In effect" is the same colour as the seal on the primary
+  // button, and for the same reason: the accent is reserved for thin marks.
+  trackOn: {backgroundColor: semanticTokens.colorText},
+  trackDisabled: {backgroundColor: semanticTokens.colorDisabledSurface},
+  // A round knob travelling inside a squared track reads as a physical switch;
+  // two capsules read as a widget.
   thumb: {
-    backgroundColor: semanticTokens.colorSurfaceRaised,
+    backgroundColor: semanticTokens.colorSurface,
     borderRadius: semanticTokens.radiusFull,
-    boxShadow: semanticTokens.elevationLow,
-    height: semanticTokens.spacingMd,
-    width: semanticTokens.spacingMd,
+    height: knobSize,
+    insetInlineStart: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'inset-inline-start',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: knobSize,
   },
+  thumbOn: {insetInlineStart: knobTravel},
   thumbDisabled: {backgroundColor: semanticTokens.colorDisabledText},
 });
 
@@ -129,6 +154,7 @@ export function Toggle({
           aria-hidden="true"
           {...stylex.props(
             styles.thumb,
+            isPressed ? styles.thumbOn : undefined,
             disabled ? styles.thumbDisabled : undefined,
           )}
         />

package/src/ToggleButton/ToggleButton.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const toggleButtonDoc = {
+  name: 'ToggleButton',
+  description: 'A button that stays pressed.',
+  props: [
+    {
+      name: 'defaultPressed',
+      description: 'Sets the initial uncontrolled state.',
+    },
+    {name: 'onPressedChange', description: 'Receives the next pressed state.'},
+    {name: 'pressed', description: 'Controls the pressed state.'},
+    {name: 'size', description: 'Selects the fixed control height.'},
+  ],
+  inheritedProps: [
+    'ButtonHTMLAttributes<HTMLButtonElement> except aria-pressed and className',
+  ],
+  example:
+    '<ToggleButton onPressedChange={setBold} pressed={bold}>Bold</ToggleButton>',
+  storyId: 'core-toggle-button--default',
+} satisfies ComponentDoc;

package/src/ToggleButton/ToggleButton.tsx

@@ -0,0 +1,163 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type ButtonHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {ControlSize} from '../Button/index.js';
+
+const styles = stylex.create({
+  // The block-end edge is carried at the focus weight in every state so the
+  // pressed mark can arrive as colour alone, without the box changing size.
+  base: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurface,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.focusWidth,
+    borderBlockStartStyle: semanticTokens.borderStyle,
+    borderBlockStartWidth: semanticTokens.borderWidth,
+    borderInlineStyle: semanticTokens.borderStyle,
+    borderInlineWidth: semanticTokens.borderWidth,
+    borderRadius: semanticTokens.radiusElement,
+    boxSizing: 'border-box',
+    cursor: 'pointer',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    justifyContent: 'center',
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':disabled': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      borderBlockEndColor: semanticTokens.borderDisabled,
+      borderBlockStartColor: semanticTokens.borderDisabled,
+      borderInlineEndColor: semanticTokens.borderDisabled,
+      borderInlineStartColor: semanticTokens.borderDisabled,
+      color: semanticTokens.colorDisabledText,
+      cursor: 'default',
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  sm: {
+    fontSize: semanticTokens.fontSizeSm,
+    height: semanticTokens.sizeControlSm,
+    paddingInline: semanticTokens.spacingSm,
+  },
+  md: {
+    fontSize: semanticTokens.fontSizeMd,
+    height: semanticTokens.sizeControlMd,
+    paddingInline: semanticTokens.spacingMd,
+  },
+  lg: {
+    fontSize: semanticTokens.fontSizeMd,
+    height: semanticTokens.sizeControlLg,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  // Only the state that can still be entered carries a hover or a press.
+  unpressed: {
+    borderBlockEndColor: semanticTokens.borderStrong,
+    borderBlockStartColor: semanticTokens.borderStrong,
+    borderInlineEndColor: semanticTokens.borderStrong,
+    borderInlineStartColor: semanticTokens.borderStrong,
+    color: semanticTokens.colorTextSecondary,
+    fontWeight: semanticTokens.fontWeightRegular,
+    ':active:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayActive,
+      borderBlockEndColor: semanticTokens.borderInteractive,
+      borderBlockStartColor: semanticTokens.borderInteractive,
+      borderInlineEndColor: semanticTokens.borderInteractive,
+      borderInlineStartColor: semanticTokens.borderInteractive,
+    },
+    ':hover:not(:disabled):not(:active)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      borderBlockEndColor: semanticTokens.borderInteractive,
+      borderBlockStartColor: semanticTokens.borderInteractive,
+      borderInlineEndColor: semanticTokens.borderInteractive,
+      borderInlineStartColor: semanticTokens.borderInteractive,
+    },
+  },
+  // Pressed is a mark and a change of ink, never a filled block. The mark is
+  // the same ink underline a selected tab draws, one weight heavier than the
+  // edge it replaces, so a pressed toggle and a current tab read as one idea.
+  pressed: {
+    borderBlockEndColor: semanticTokens.colorText,
+    borderBlockStartColor: semanticTokens.borderStrong,
+    borderInlineEndColor: semanticTokens.borderStrong,
+    borderInlineStartColor: semanticTokens.borderStrong,
+    color: semanticTokens.colorText,
+    fontWeight: semanticTokens.fontWeightMedium,
+  },
+});
+
+type SharedToggleButtonProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'aria-pressed' | 'className'
+> & {
+  readonly onPressedChange?: (pressed: boolean) => void;
+  readonly size?: ControlSize;
+};
+
+type ControlledToggleButtonProps = SharedToggleButtonProps & {
+  readonly defaultPressed?: never;
+  readonly onPressedChange: (pressed: boolean) => void;
+  readonly pressed: boolean;
+};
+
+type UncontrolledToggleButtonProps = SharedToggleButtonProps & {
+  readonly defaultPressed?: boolean;
+  readonly pressed?: never;
+};
+
+/** Props for a button that stays pressed. */
+export type ToggleButtonProps =
+  ControlledToggleButtonProps | UncontrolledToggleButtonProps;
+
+/**
+ * A button that stays pressed. It reports state through `aria-pressed`, which
+ * is what separates it from `Switch`: this is a command that stays on, not a
+ * setting that applies on its own.
+ */
+export function ToggleButton({
+  children,
+  defaultPressed = false,
+  disabled,
+  onClick,
+  onPressedChange,
+  pressed,
+  size = 'md',
+  type = 'button',
+  ...props
+}: ToggleButtonProps) {
+  const [internalPressed, setInternalPressed] = useState(defaultPressed);
+  const isPressed = pressed ?? internalPressed;
+
+  return (
+    <button
+      {...props}
+      aria-pressed={isPressed}
+      disabled={disabled}
+      onClick={(event) => {
+        const next = !isPressed;
+        if (pressed === undefined) {
+          setInternalPressed(next);
+        }
+        onPressedChange?.(next);
+        onClick?.(event);
+      }}
+      {...stylex.props(
+        styles.base,
+        styles[size],
+        isPressed ? styles.pressed : styles.unpressed,
+      )}
+      type={type}
+    >
+      {children}
+    </button>
+  );
+}

package/src/ToggleButton/index.ts

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

package/src/ToggleButtonGroup/ToggleButtonGroup.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const toggleButtonGroupDoc = {
+  name: 'ToggleButtonGroup',
+  description: 'A set of toggle buttons acting as one control.',
+  props: [
+    {name: 'label', description: 'Names the group for assistive technology.'},
+    {name: 'onValueChange', description: 'Receives the next selection.'},
+    {name: 'options', description: 'Supplies the options in reading order.'},
+    {
+      name: 'orientation',
+      description: 'Selects the axis arrow keys travel along.',
+    },
+    {name: 'selectionMode', description: 'Allows one option or several.'},
+    {name: 'size', description: 'Selects the fixed control height.'},
+    {name: 'value', description: 'Controls which options are pressed.'},
+  ],
+  inheritedProps: ['None; ToggleButtonGroup owns its group element'],
+  example:
+    '<ToggleButtonGroup label="Alignment" onValueChange={setAlign} options={aligns} value={align} />',
+  storyId: 'core-toggle-button-group--default',
+} satisfies ComponentDoc;

package/src/ToggleButtonGroup/ToggleButtonGroup.tsx

@@ -0,0 +1,108 @@
+import {useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {ControlSize} from '../Button/index.js';
+import {useListFocus, type ListOrientation} from '../hooks/useListFocus.js';
+import {ToggleButton} from '../ToggleButton/index.js';
+
+const styles = stylex.create({
+  group: {display: 'inline-flex', gap: semanticTokens.spacingXs},
+  horizontal: {flexDirection: 'row', flexWrap: 'wrap'},
+  vertical: {alignItems: 'stretch', flexDirection: 'column'},
+});
+
+/** One option inside a toggle group. */
+export interface ToggleOption {
+  readonly disabled?: boolean;
+  readonly label: ReactNode;
+  readonly value: string;
+}
+
+interface SharedProps {
+  readonly label: string;
+  readonly options: readonly ToggleOption[];
+  readonly orientation?: ListOrientation;
+  readonly size?: ControlSize;
+}
+
+interface SingleProps extends SharedProps {
+  readonly onValueChange: (value: string) => void;
+  readonly selectionMode?: 'single';
+  readonly value: string;
+}
+
+interface MultipleProps extends SharedProps {
+  readonly onValueChange: (value: readonly string[]) => void;
+  readonly selectionMode: 'multiple';
+  readonly value: readonly string[];
+}
+
+/** Props for a set of toggle buttons acting as one control. */
+export type ToggleButtonGroupProps = MultipleProps | SingleProps;
+
+/**
+ * A row of toggle buttons that behaves as one control: one tab stop, arrow
+ * keys between options.
+ *
+ * `single` keeps exactly one option pressed, which is what `SegmentedControl`
+ * also does — prefer that when the options are views of the same thing, and
+ * this when they are formatting-style toggles that happen to be exclusive.
+ */
+export function ToggleButtonGroup(props: ToggleButtonGroupProps) {
+  const {label, options, orientation = 'horizontal', size = 'md'} = props;
+  const groupRef = useRef<HTMLDivElement>(null);
+  const {onKeyDown} = useListFocus(groupRef, {orientation});
+
+  const isPressed = (value: string) =>
+    props.selectionMode === 'multiple'
+      ? props.value.includes(value)
+      : props.value === value;
+
+  // One tab stop for the whole group: the tab order lands on whichever option
+  // is already pressed, and the arrow keys take it from there.
+  const tabStopValue =
+    options.find((option) => !option.disabled && isPressed(option.value))
+      ?.value ?? options.find((option) => !option.disabled)?.value;
+
+  function choose(value: string, pressed: boolean) {
+    if (props.selectionMode === 'multiple') {
+      props.onValueChange(
+        pressed
+          ? [...props.value, value]
+          : props.value.filter((entry) => entry !== value),
+      );
+      return;
+    }
+    // A single-select group never empties: pressing the active option again
+    // would leave the control saying nothing is chosen.
+    if (pressed) {
+      props.onValueChange(value);
+    }
+  }
+
+  return (
+    <div
+      aria-label={label}
+      onKeyDown={onKeyDown}
+      ref={groupRef}
+      role="group"
+      {...stylex.props(styles.group, styles[orientation])}
+    >
+      {options.map((option) => (
+        <ToggleButton
+          disabled={option.disabled ?? false}
+          key={option.value}
+          onPressedChange={(pressed) => {
+            choose(option.value, pressed);
+          }}
+          pressed={isPressed(option.value)}
+          size={size}
+          tabIndex={option.value === tabStopValue ? 0 : -1}
+        >
+          {option.label}
+        </ToggleButton>
+      ))}
+    </div>
+  );
+}

package/src/ToggleButtonGroup/index.ts

@@ -0,0 +1,5 @@
+export {
+  ToggleButtonGroup,
+  type ToggleButtonGroupProps,
+  type ToggleOption,
+} from './ToggleButtonGroup.js';

package/src/Token/Token.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const tokenDoc = {
+  name: 'Token',
+  description: 'Shows one discrete value as a removable chip.',
+  props: [
+    {name: 'children', description: 'Supplies the value label.'},
+    {name: 'leading', description: 'Places content before the label.'},
+    {
+      name: 'onRemove',
+      description: 'Adds a remove control and receives its click.',
+    },
+    {name: 'removeLabel', description: 'Names the remove control.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except children and className',
+  ],
+  example: '<Token onRemove={clear} removeLabel="Remove Ada">Ada</Token>',
+  storyId: 'core-token--default',
+} satisfies ComponentDoc;

package/src/Token/Token.tsx

@@ -0,0 +1,131 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useInternationalization} from '../i18n/index.js';
+import {Icon} from '../Icon/index.js';
+
+const styles = stylex.create({
+  // The value the reader entered is current, so it takes the first rank of
+  // ink; the control that clears it is merely available and stays a rank
+  // below. That is what separates a token from a neutral badge, rather than a
+  // second fill.
+  token: {
+    alignItems: 'center',
+    // Paper, not the well. A token's usual home is inside a Tokenizer, whose
+    // field is the well colour too — same fill, no border, and the token had
+    // no edge at all. Lifting it to the surface rank says what it is: a thing
+    // resting in the field rather than part of the field.
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    gap: semanticTokens.spacingXs,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    maxWidth: '100%',
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+  },
+  removable: {paddingInlineEnd: semanticTokens.spacingXs},
+  label: {
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
+  remove: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusInner,
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    flexShrink: 0,
+    padding: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    // The visual box tracks the token; the reachable box stays a full target.
+    '::before': {
+      content: '',
+      height: semanticTokens.sizeHitTarget,
+      insetBlockStart: '50%',
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translate(-50%, -50%)',
+      width: semanticTokens.sizeHitTarget,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled)': {color: semanticTokens.colorText},
+  },
+});
+
+/** Props for one discrete value shown as a chip. */
+export interface TokenProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly leading?: ReactNode;
+  readonly onRemove?: () => void;
+  readonly removeLabel?: string;
+}
+
+/**
+ * Shows one discrete value the reader has entered or chosen. When it can be
+ * removed the control carries its own name, so a keyboard reader knows which
+ * token a given button clears.
+ */
+export function Token({
+  children,
+  leading,
+  onRemove,
+  removeLabel,
+  ...props
+}: TokenProps) {
+  const {messages} = useInternationalization();
+
+  return (
+    <span
+      {...props}
+      {...stylex.props(
+        styles.token,
+        onRemove !== undefined && styles.removable,
+      )}
+    >
+      {leading}
+      <span {...stylex.props(styles.label)}>{children}</span>
+      {onRemove === undefined ? null : (
+        <button
+          aria-label={removeLabel ?? messages.remove}
+          onClick={onRemove}
+          {...stylex.props(styles.remove)}
+          type="button"
+        >
+          <Icon size="sm">
+            <path
+              d="m6 6 12 12M18 6 6 18"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+            />
+          </Icon>
+        </button>
+      )}
+    </span>
+  );
+}

package/src/Token/index.ts

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

package/src/Tokenizer/Tokenizer.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const tokenizerDoc = {
+  name: 'Tokenizer',
+  description: 'Turns typed text into discrete removable tokens.',
+  props: [
+    {name: 'label', description: 'Names the entry field.'},
+    {name: 'onValueChange', description: 'Receives the next set of tokens.'},
+    {name: 'placeholder', description: 'Hints at what to type.'},
+    {
+      name: 'removeLabel',
+      description: 'Builds the name of each remove control.',
+    },
+    {name: 'value', description: 'Controls the current tokens.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, defaultValue, and onChange',
+  ],
+  example: '<Tokenizer label="Tags" onValueChange={setTags} value={tags} />',
+  storyId: 'core-tokenizer--default',
+} satisfies ComponentDoc;