@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/ComplexSelector/ComplexSelector.tsx

@@ -0,0 +1,213 @@
+import * as stylex from '@stylexjs/stylex';
+import type {ChangeEvent, SelectHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFieldControl} from '../Field/index.js';
+import type {SelectorOption} from '../Selector/index.js';
+
+const styles = stylex.create({
+  // An input sinks below the card it sits on, and a select is an input: the
+  // muted fill and the strong hairline are what put it on the same rung as the
+  // text fields it shares a form with. Painted on `colorSurface` it read as a
+  // card among wells.
+  // The well is the frame, because the mark that says "this opens" is ours
+  // now. Left native, a select wore whichever arrow the platform draws — a
+  // blue chevron on one, a grey triangle on another — in the corner of a
+  // field this system had otherwise drawn to the hairline.
+  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',
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':focus-within': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {borderColor: semanticTokens.borderInteractive},
+  },
+  frameDisabled: {
+    backgroundColor: semanticTokens.colorDisabledSurface,
+    borderColor: semanticTokens.borderDisabled,
+    ':hover': {borderColor: semanticTokens.borderDisabled},
+  },
+  frameInvalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-within': {borderColor: semanticTokens.statusDangerText},
+    ':hover': {borderColor: semanticTokens.statusDangerText},
+  },
+  // The chevron: two edges of an empty square stood on a corner, the same way
+  // the checkbox draws its tick and the number field its steps. It takes its
+  // colour from the palette, which is the whole point of not letting the
+  // engine draw it. `aria-hidden`, because the select already announces that
+  // it is a select.
+  chevron: {
+    borderBlockEndColor: semanticTokens.colorTextSecondary,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    borderInlineEndColor: semanticTokens.colorTextSecondary,
+    borderInlineEndStyle: semanticTokens.borderStyle,
+    borderInlineEndWidth: semanticTokens.borderWidth,
+    blockSize: semanticTokens.spacingSm,
+    inlineSize: semanticTokens.spacingSm,
+    insetBlockStart: '50%',
+    insetInlineEnd: semanticTokens.spacingSm,
+    pointerEvents: 'none',
+    position: 'absolute',
+    transform: 'translateY(-70%) rotate(45deg)',
+  },
+  chevronDisabled: {
+    borderBlockEndColor: semanticTokens.colorDisabledText,
+    borderInlineEndColor: semanticTokens.colorDisabledText,
+  },
+  control: {
+    appearance: 'none',
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    cursor: 'pointer',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    // Trailing room for the chevron, so the longest option stops short of it.
+    paddingInlineEnd: `calc(${semanticTokens.spacingSm} + ${semanticTokens.spacingLg})`,
+    paddingInlineStart: semanticTokens.spacingSm,
+    width: '100%',
+    ':disabled': {color: semanticTokens.colorDisabledText, cursor: 'default'},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+  invalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-visible': {borderColor: semanticTokens.statusDangerText},
+    ':hover:not(:disabled)': {borderColor: semanticTokens.statusDangerText},
+  },
+});
+
+/** A named group of related options. */
+export interface SelectorGroup {
+  readonly disabled?: boolean;
+  readonly label: string;
+  readonly options: readonly SelectorOption[];
+}
+
+type SharedComplexSelectorProps = Omit<
+  SelectHTMLAttributes<HTMLSelectElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange' | 'value'
+> & {
+  readonly groups: readonly SelectorGroup[];
+  readonly onValueChange?: (value: string) => void;
+  readonly placeholder?: string;
+};
+
+type ControlledComplexSelectorProps = SharedComplexSelectorProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: string) => void;
+  readonly value: string;
+};
+
+type UncontrolledComplexSelectorProps = SharedComplexSelectorProps & {
+  readonly defaultValue?: string;
+  readonly value?: never;
+};
+
+/** Props for choosing one option from grouped lists. */
+export type ComplexSelectorProps =
+  ControlledComplexSelectorProps | UncontrolledComplexSelectorProps;
+
+/**
+ * Chooses one option from grouped lists. Groups become native `optgroup`
+ * elements, so a screen reader announces which group an option belongs to.
+ */
+export function ComplexSelector({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  disabled,
+  groups,
+  id,
+  onValueChange,
+  placeholder,
+  required,
+  ...props
+}: ComplexSelectorProps) {
+  const field = useFieldControl();
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const invalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function handleChange(event: ChangeEvent<HTMLSelectElement>) {
+    onValueChange?.(event.currentTarget.value);
+  }
+
+  return (
+    <span
+      {...stylex.props(
+        styles.frame,
+        invalid && !disabled ? styles.frameInvalid : undefined,
+        disabled ? styles.frameDisabled : undefined,
+      )}
+    >
+      <select
+        {...props}
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        onChange={handleChange}
+        required={required ?? field?.required}
+        {...stylex.props(styles.control)}
+      >
+        {placeholder === undefined ? null : (
+          <option disabled value="">
+            {placeholder}
+          </option>
+        )}
+        {groups.map((group) => (
+          <optgroup
+            disabled={group.disabled ?? false}
+            key={group.label}
+            label={group.label}
+          >
+            {group.options.map((option) => (
+              <option
+                disabled={option.disabled ?? false}
+                key={option.value}
+                value={option.value}
+              >
+                {option.label}
+              </option>
+            ))}
+          </optgroup>
+        ))}
+      </select>
+      <span
+        aria-hidden="true"
+        {...stylex.props(
+          styles.chevron,
+          disabled ? styles.chevronDisabled : undefined,
+        )}
+      />
+    </span>
+  );
+}

package/src/ComplexSelector/index.ts

@@ -0,0 +1,5 @@
+export {
+  ComplexSelector,
+  type ComplexSelectorProps,
+  type SelectorGroup,
+} from './ComplexSelector.js';

package/src/ContextMenu/ContextMenu.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const contextMenuDoc = {
+  name: 'ContextMenu',
+  description: 'Opens a menu at the pointer on a secondary click.',
+  props: [
+    {
+      name: 'children',
+      description: 'Supplies the region that accepts the click.',
+    },
+    {name: 'label', description: 'Names the menu for assistive technology.'},
+    {name: 'menu', description: 'Supplies the menu items.'},
+  ],
+  inheritedProps: ['None; ContextMenu owns its region and menu'],
+  example:
+    '<ContextMenu label="Row actions" menu={items}><TableRow>...</TableRow></ContextMenu>',
+  storyId: 'core-context-menu--default',
+} satisfies ComponentDoc;

package/src/ContextMenu/ContextMenu.tsx

@@ -0,0 +1,61 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, useState, type MouseEvent, type ReactNode} from 'react';
+
+import {DropdownMenu} from '../DropdownMenu/index.js';
+
+const styles = stylex.create({
+  anchor: {
+    height: 0,
+    position: 'fixed',
+    width: 0,
+  },
+});
+
+/** Props for a menu opened by a secondary click on a region. */
+export interface ContextMenuProps {
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly menu: ReactNode;
+}
+
+/**
+ * Opens a menu at the pointer on a secondary click. The menu anchors to a
+ * zero-size marker placed at the click point, so it positions and flips with
+ * the same rules as any other anchored surface.
+ */
+export function ContextMenu({children, label, menu}: ContextMenuProps) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [point, setPoint] = useState<{left: number; top: number} | undefined>(
+    undefined,
+  );
+
+  function handleContextMenu(event: MouseEvent<HTMLDivElement>) {
+    event.preventDefault();
+    setPoint({left: event.clientX, top: event.clientY});
+  }
+
+  return (
+    <>
+      <div onContextMenu={handleContextMenu}>{children}</div>
+      {point === undefined ? null : (
+        <span
+          aria-hidden="true"
+          ref={anchorRef}
+          {...stylex.props(styles.anchor)}
+          style={{left: point.left, top: point.top}}
+        />
+      )}
+      <DropdownMenu
+        anchorRef={anchorRef}
+        label={label}
+        onDismiss={() => {
+          setPoint(undefined);
+        }}
+        open={point !== undefined}
+        placement="bottom"
+      >
+        {menu}
+      </DropdownMenu>
+    </>
+  );
+}

package/src/ContextMenu/index.ts

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

package/src/DateInput/DateInput.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const dateInputDoc = {
+  name: 'DateInput',
+  description: 'Accepts one calendar date as an ISO string.',
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled date.'},
+    {name: 'onValueChange', description: 'Receives the ISO date string.'},
+    {name: 'value', description: 'Controls the current ISO date string.'},
+  ],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except children, className, defaultValue, onChange, type, and value',
+  ],
+  example: '<DateInput onValueChange={setReleaseDate} value={releaseDate} />',
+  storyId: 'core-date-input--default',
+} satisfies ComponentDoc;

package/src/DateInput/DateInput.tsx

@@ -0,0 +1,9 @@
+import {TemporalInput, type TemporalInputProps} from './TemporalInput.js';
+
+/** Props for a calendar-date field. */
+export type DateInputProps = TemporalInputProps;
+
+/** Accepts one calendar date, exchanged as an ISO `YYYY-MM-DD` string. */
+export function DateInput(props: DateInputProps) {
+  return <TemporalInput {...props} type="date" />;
+}

package/src/DateInput/TemporalInput.tsx

@@ -0,0 +1,305 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useRef,
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Icon} from '../Icon/index.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. What it holds is a figure, so it is set in
+  // the mono face with tabular figures — a date whose digits shift width as
+  // the reader steps a month is the loudest thing a quiet field can do, and
+  // two of these side by side in a range would never line up.
+  // The well is the frame, because the trigger lives inside it. What the
+  // engine used to put there was its own glyph — a blue calendar in Blink, a
+  // grey one in WebKit — sitting in a field this system had otherwise drawn
+  // down to the hairline.
+  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},
+  },
+  // Our own trigger, in the well rather than on it — the same column the
+  // number field gives its steppers. It opens the platform's picker, which is
+  // the half of this control worth keeping: the wheel on a phone, the reader's
+  // own date order, and the whole accessibility tree come with it.
+  trigger: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderInlineStartColor: semanticTokens.borderDefault,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.borderWidth,
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'flex',
+    flexShrink: 0,
+    inlineSize: semanticTokens.spacing2xl,
+    justifyContent: 'center',
+    padding: 0,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':active': {backgroundColor: semanticTokens.colorOverlayActive},
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: `calc(-1 * ${semanticTokens.focusOffset})`,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  control: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+    minWidth: 0,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    width: '100%',
+    // The engine's own trigger, turned off. The component draws one beside it
+    // and calls `showPicker()`, so the platform's picker still opens — this
+    // hides the glyph, not the behaviour.
+    '::-webkit-calendar-picker-indicator': {display: 'none'},
+    // The separators are not data. Set at the same weight as the figures they
+    // part, a date reads as one seven-digit run rather than as three fields.
+    '::-webkit-datetime-edit-text': {
+      color: semanticTokens.colorTextMuted,
+      paddingInline: 0,
+    },
+    ':disabled': {color: semanticTokens.colorDisabledText},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+  // An empty control shows `dd/mm/yyyy`, and it used to show it in the same
+  // ink as a real date directly above it — the reader could not tell an
+  // answered field from an unanswered one. The engine gives no selector for
+  // "no value", so the component supplies the fact it already holds.
+  empty: {
+    color: semanticTokens.colorTextMuted,
+    '::-webkit-datetime-edit': {color: semanticTokens.colorTextMuted},
+  },
+  // Read-only is not disabled: the value still reads at full strength, but the
+  // control stops looking like a well you can type into.
+  readOnly: {color: semanticTokens.colorText},
+});
+
+/** Native input types that accept a point in time. */
+export type TemporalInputType = 'date' | 'datetime-local' | 'time';
+
+const defaultPickerLabels: Record<TemporalInputType, string> = {
+  date: 'Choose a date',
+  'datetime-local': 'Choose a date and time',
+  time: 'Choose a time',
+};
+
+type SharedTemporalProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange' | 'type' | 'value'
+> & {
+  readonly onValueChange?: (value: string) => void;
+  /**
+   * Opens a picker of the caller's own instead of the platform's. `DatePicker`
+   * supplies one; without it the trigger opens the platform picker, which is
+   * the right default because that picker brings the phone wheel, the reader's
+   * date order and the accessibility tree with it.
+   */
+  readonly onPickerOpen?: () => void;
+  /** Names the control that opens the picker. */
+  readonly pickerLabel?: string;
+};
+
+type ControlledTemporalProps = SharedTemporalProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: string) => void;
+  readonly value: string;
+};
+
+type UncontrolledTemporalProps = SharedTemporalProps & {
+  readonly defaultValue?: string;
+  readonly value?: never;
+};
+
+/** Props shared by every single-value temporal field. */
+export type TemporalInputProps =
+  ControlledTemporalProps | UncontrolledTemporalProps;
+
+/**
+ * @internal Shared native implementation for the temporal inputs. Values are
+ * exchanged in the ISO form the platform control uses, never a localized one.
+ */
+export function TemporalInput({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  defaultValue = '',
+  disabled,
+  id,
+  onPickerOpen,
+  onValueChange,
+  pickerLabel,
+  readOnly,
+  required,
+  type,
+  value,
+  ...props
+}: TemporalInputProps & {readonly type: TemporalInputType}) {
+  const field = useFieldControl();
+  const controlRef = useRef<HTMLInputElement>(null);
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const invalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function handleChange(event: ChangeEvent<HTMLInputElement>) {
+    const next = event.currentTarget.value;
+    if (value === undefined) {
+      setInternalValue(next);
+    }
+    onValueChange?.(next);
+  }
+
+  const shown = value ?? internalValue;
+  const opensPicker = !disabled && !readOnly;
+
+  // `showPicker` is the only way to open the platform picker once its own
+  // glyph is hidden. Where it is missing the trigger is not drawn at all — a
+  // control that does nothing when pressed is worse than one that is absent,
+  // and the field still types and steps on the keyboard without it.
+  function openPicker() {
+    if (onPickerOpen) {
+      onPickerOpen();
+      return;
+    }
+    const control = controlRef.current;
+    if (typeof control?.showPicker === 'function') {
+      control.showPicker();
+    }
+  }
+
+  return (
+    <span
+      {...stylex.props(
+        styles.frame,
+        readOnly && !disabled ? styles.frameReadOnly : undefined,
+        invalid && !disabled ? styles.frameInvalid : undefined,
+        disabled ? styles.frameDisabled : undefined,
+      )}
+    >
+      <input
+        {...props}
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        onChange={handleChange}
+        readOnly={readOnly}
+        ref={controlRef}
+        required={required ?? field?.required}
+        {...stylex.props(
+          styles.control,
+          shown === '' && !disabled ? styles.empty : undefined,
+          readOnly && !disabled ? styles.readOnly : undefined,
+        )}
+        type={type}
+        value={shown}
+      />
+      {opensPicker ? (
+        <button
+          aria-label={pickerLabel ?? defaultPickerLabels[type]}
+          onClick={openPicker}
+          type="button"
+          {...(onPickerOpen ? {} : {tabIndex: -1})}
+          {...stylex.props(styles.trigger)}
+        >
+          <Icon size="sm" tone="inherit">
+            {type === 'time' ? (
+              <>
+                <circle
+                  cx="12"
+                  cy="12"
+                  fill="none"
+                  r="9"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                />
+                <path
+                  d="M12 7v5l3 2"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeLinecap="round"
+                  strokeWidth="2"
+                />
+              </>
+            ) : (
+              <>
+                <rect
+                  fill="none"
+                  height="16"
+                  rx="2"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  width="18"
+                  x="3"
+                  y="5"
+                />
+                <path
+                  d="M3 10h18M8 3v4M16 3v4"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeLinecap="round"
+                  strokeWidth="2"
+                />
+              </>
+            )}
+          </Icon>
+        </button>
+      ) : null}
+    </span>
+  );
+}

package/src/DateInput/index.ts

@@ -0,0 +1,6 @@
+export {DateInput, type DateInputProps} from './DateInput.js';
+export {
+  TemporalInput,
+  type TemporalInputProps,
+  type TemporalInputType,
+} from './TemporalInput.js';

package/src/DatePicker/DatePicker.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const datePickerDoc = {
+  name: 'DatePicker',
+  description: "Picks a date from this system's own month grid.",
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled date.'},
+    {name: 'id', description: 'Names the field a label points at.'},
+    {name: 'label', description: 'Names the month grid.', required: true},
+    {name: 'max', description: 'Refuses days after this ISO date.'},
+    {name: 'min', description: 'Refuses days before this ISO date.'},
+    {name: 'onValueChange', description: 'Receives the ISO date string.'},
+    {name: 'value', description: 'Controls the current ISO date string.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except children, className, defaultValue, and onChange',
+  ],
+  example:
+    '<DatePicker label="Release date" onValueChange={setDate} value={date} />',
+  storyId: 'core-date-picker--default',
+} satisfies ComponentDoc;