@misoto22/kioku-ui 0.1.0 → 0.2.0

package/src/DatePicker/DatePicker.tsx

@@ -0,0 +1,138 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, useState, type HTMLAttributes} from 'react';
+
+import {Calendar} from '../Calendar/index.js';
+import {DateInput} from '../DateInput/index.js';
+import {Popover} from '../Popover/index.js';
+
+const styles = stylex.create({
+  // The anchor is the whole field, so the sheet lines up with the well rather
+  // than with the small control that opened it.
+  root: {display: 'block', position: 'relative', width: '100%'},
+});
+
+type SharedDatePickerProps = Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange'
+> & {
+  readonly disabled?: boolean;
+  /**
+   * Given to the field, not to the wrapper — a `<label for>` beside this
+   * control has to reach the input the reader types into.
+   */
+  readonly id?: string;
+  /** Names the month grid for assistive technology. */
+  readonly label: string;
+  readonly max?: string;
+  readonly min?: string;
+  readonly onValueChange?: (value: string) => void;
+  readonly pickerLabel?: string;
+  readonly readOnly?: boolean;
+};
+
+type ControlledDatePickerProps = SharedDatePickerProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: string) => void;
+  readonly value: string;
+};
+
+type UncontrolledDatePickerProps = SharedDatePickerProps & {
+  readonly defaultValue?: string;
+  readonly value?: never;
+};
+
+/** Props for a date field whose picker this system draws. */
+export type DatePickerProps =
+  ControlledDatePickerProps | UncontrolledDatePickerProps;
+
+/**
+ * A date field with a month grid of this system's own instead of the engine's.
+ *
+ * `DateInput` remains the right choice for a lone date: leaving the platform
+ * picker in place is what keeps the wheel on a phone, the reader's own date
+ * order and the whole accessibility tree for free. Reach for this one when the
+ * sheet itself has to belong to the page — a range, a set of shortcuts, two
+ * months side by side — because none of those exist in any engine's picker.
+ */
+export function DatePicker({
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  defaultValue = '',
+  disabled,
+  id,
+  label,
+  max,
+  min,
+  onValueChange,
+  pickerLabel,
+  readOnly,
+  value,
+  ...props
+}: DatePickerProps) {
+  // `label` names the grid, and a reader who never opens the grid would meet
+  // an unnamed field. An explicit name wins; an `id` means the caller has
+  // wired a `<label for>` of its own, which anything set here would override.
+  const fieldLabel =
+    ariaLabel ??
+    (ariaLabelledBy === undefined && id === undefined ? label : undefined);
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [open, setOpen] = useState(false);
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const shown = value ?? internalValue;
+
+  function commit(next: string) {
+    if (value === undefined) {
+      setInternalValue(next);
+    }
+    onValueChange?.(next);
+  }
+
+  // Closing returns the reader to the field they left, whether the sheet was
+  // dismissed or a day was chosen. A picker that drops focus on the document
+  // costs a keyboard reader the whole form.
+  function close() {
+    setOpen(false);
+    anchorRef.current?.querySelector('input')?.focus();
+  }
+
+  return (
+    <span {...props} ref={anchorRef} {...stylex.props(styles.root)}>
+      <DateInput
+        {...(fieldLabel === undefined ? {} : {'aria-label': fieldLabel})}
+        {...(ariaLabelledBy === undefined
+          ? {}
+          : {'aria-labelledby': ariaLabelledBy})}
+        disabled={disabled}
+        {...(id === undefined ? {} : {id})}
+        {...(max === undefined ? {} : {max})}
+        {...(min === undefined ? {} : {min})}
+        onPickerOpen={() => {
+          setOpen(true);
+        }}
+        onValueChange={commit}
+        {...(pickerLabel === undefined ? {} : {pickerLabel})}
+        readOnly={readOnly}
+        value={shown}
+      />
+      <Popover
+        alignment="start"
+        anchorRef={anchorRef}
+        onDismiss={close}
+        open={open}
+        placement="bottom"
+        role="presentation"
+      >
+        <Calendar
+          label={label}
+          {...(max === undefined ? {} : {max})}
+          {...(min === undefined ? {} : {min})}
+          onValueChange={(next) => {
+            commit(next);
+            close();
+          }}
+          value={shown}
+        />
+      </Popover>
+    </span>
+  );
+}

package/src/DatePicker/index.ts

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

package/src/DateRangeInput/DateRangeInput.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const dateRangeInputDoc = {
+  name: 'DateRangeInput',
+  description: 'Accepts a start and end date that cannot cross.',
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled range.'},
+    {name: 'endLabel', description: 'Names the end control.'},
+    {name: 'legend', description: 'States what the range covers.'},
+    {name: 'onValueChange', description: 'Receives the next range.'},
+    {name: 'startLabel', description: 'Names the start control.'},
+    {name: 'value', description: 'Controls the current range.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLFieldSetElement> except children, className, defaultValue, and onChange',
+  ],
+  example:
+    '<DateRangeInput legend="Reporting period" onValueChange={setRange} value={range} />',
+  storyId: 'core-date-range-input--default',
+} satisfies ComponentDoc;

package/src/DateRangeInput/DateRangeInput.tsx

@@ -0,0 +1,159 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, useState, type HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {DatePicker} from '../DatePicker/index.js';
+
+// The narrowest a date control stays legible at before the pair should stack.
+// The spacing scale has no single step that measures it.
+const boundMinimumWidth = `calc(${semanticTokens.spacing2xl} * 6)`;
+
+const styles = stylex.create({
+  group: {
+    borderStyle: 'none',
+    borderWidth: 0,
+    display: 'flex',
+    flexWrap: 'wrap',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingMd,
+    margin: 0,
+    padding: 0,
+  },
+  // The question the pair asks, set in the display face: a mincho line is how
+  // this system titles a group, and it is what keeps the legend from reading
+  // as a third field label sitting above two others.
+  legend: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeSm,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    // A legend is not a flex item: the browser lifts it out of the fieldset's
+    // formatting context and draws it in the border box, so the group's `gap`
+    // never reaches it and the first row sat flush against the question. The
+    // step has to be spent here, and it has to match the group's own gap.
+    // The `flexBasis: 100%` that used to sit here was the same mistake read
+    // the other way round: it assumed the legend was a flex item that needed
+    // forcing onto its own line. It never was one, and the two bounds sat side
+    // by side either way.
+    marginBlockEnd: semanticTokens.spacingMd,
+    padding: 0,
+  },
+  bound: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexGrow: 1,
+    gap: semanticTokens.spacingXs,
+    minWidth: boundMinimumWidth,
+  },
+  // "Start" and "End" are eyebrows, not labels. The legend already asks the
+  // question; these two only say which end of it a control holds, and set at
+  // the same size and weight as the legend they competed with it.
+  label: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+  },
+});
+
+/** A start and end date, either of which may still be empty. */
+export interface DateRange {
+  readonly end: string;
+  readonly start: string;
+}
+
+type SharedRangeProps = Omit<
+  HTMLAttributes<HTMLFieldSetElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange'
+> & {
+  readonly endLabel?: string;
+  readonly legend: string;
+  readonly onValueChange?: (value: DateRange) => void;
+  readonly startLabel?: string;
+};
+
+type ControlledRangeProps = SharedRangeProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: DateRange) => void;
+  readonly value: DateRange;
+};
+
+type UncontrolledRangeProps = SharedRangeProps & {
+  readonly defaultValue?: DateRange;
+  readonly value?: never;
+};
+
+/** Props for a start-to-end date range. */
+export type DateRangeInputProps = ControlledRangeProps | UncontrolledRangeProps;
+
+const emptyRange: DateRange = {end: '', start: ''};
+
+/**
+ * Accepts a start and an end date. The end control refuses dates before the
+ * start, so an impossible range cannot be entered in the first place.
+ *
+ * Each bound is a `DatePicker` rather than a `DateInput`: no engine offers a
+ * range picker, and two platform pickers side by side cannot show the reader
+ * that the second is bounded by the first. Two grids of this system's own can,
+ * because the bound is passed to them as `min` and `max`.
+ */
+export function DateRangeInput({
+  defaultValue,
+  endLabel = 'End',
+  legend,
+  onValueChange,
+  startLabel = 'Start',
+  value,
+  ...props
+}: DateRangeInputProps) {
+  const startId = useId();
+  const endId = useId();
+  const [internalValue, setInternalValue] = useState(
+    defaultValue ?? emptyRange,
+  );
+  const range = value ?? internalValue;
+
+  function update(next: DateRange) {
+    if (value === undefined) {
+      setInternalValue(next);
+    }
+    onValueChange?.(next);
+  }
+
+  return (
+    <fieldset {...props} {...stylex.props(styles.group)}>
+      <legend {...stylex.props(styles.legend)}>{legend}</legend>
+      <span {...stylex.props(styles.bound)}>
+        <label htmlFor={startId} {...stylex.props(styles.label)}>
+          {startLabel}
+        </label>
+        <DatePicker
+          id={startId}
+          label={startLabel}
+          {...(range.end === '' ? {} : {max: range.end})}
+          onValueChange={(start) => {
+            update({...range, start});
+          }}
+          value={range.start}
+        />
+      </span>
+      <span {...stylex.props(styles.bound)}>
+        <label htmlFor={endId} {...stylex.props(styles.label)}>
+          {endLabel}
+        </label>
+        <DatePicker
+          id={endId}
+          label={endLabel}
+          {...(range.start === '' ? {} : {min: range.start})}
+          onValueChange={(end) => {
+            update({...range, end});
+          }}
+          value={range.end}
+        />
+      </span>
+    </fieldset>
+  );
+}

package/src/DateRangeInput/index.ts

@@ -0,0 +1,5 @@
+export {
+  DateRangeInput,
+  type DateRange,
+  type DateRangeInputProps,
+} from './DateRangeInput.js';

package/src/DateTimeInput/DateTimeInput.doc.ts

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

package/src/DateTimeInput/DateTimeInput.tsx

@@ -0,0 +1,9 @@
+import {TemporalInput, type TemporalInputProps} from '../DateInput/index.js';
+
+/** Props for a datetime-local field. */
+export type DateTimeInputProps = TemporalInputProps;
+
+/** Accepts one local date and time, exchanged as an ISO string. */
+export function DateTimeInput(props: DateTimeInputProps) {
+  return <TemporalInput {...props} type="datetime-local" />;
+}

package/src/DateTimeInput/index.ts

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

package/src/Dialog/Dialog.doc.ts

@@ -0,0 +1,27 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const dialogDoc = {
+  name: 'Dialog',
+  description: 'Interrupts the page with a focus-trapped modal surface.',
+  props: [
+    {name: 'children', description: 'Supplies the dialog body.'},
+    {name: 'description', description: 'Adds a described-by summary line.'},
+    {
+      name: 'dismissOnOutsideClick',
+      description: 'Allows a click on the scrim to close the dialog.',
+    },
+    {name: 'footer', description: 'Places actions at the end of the surface.'},
+    {
+      name: 'onDismiss',
+      description: 'Runs on Escape or an allowed outside click.',
+    },
+    {name: 'open', description: 'Controls whether the dialog renders.'},
+    {name: 'size', description: 'Selects the maximum surface width.'},
+    {name: 'title', description: 'Names the dialog for assistive technology.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, role, and title',
+  ],
+  example: '<Dialog onDismiss={close} open={open} title="Publish">...</Dialog>',
+  storyId: 'core-dialog--default',
+} satisfies ComponentDoc;

package/src/Dialog/Dialog.tsx

@@ -0,0 +1,160 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {Overlay} from '../Overlay/index.js';
+
+// The scale stops at 38px, so the three surface widths are named multiples of
+// it rather than the rem literals a dialog would otherwise reach for.
+const surfaceWidthSm = `calc(${semanticTokens.spacing2xl} * 10)`;
+const surfaceWidthMd = `calc(${semanticTokens.spacing2xl} * 14)`;
+const surfaceWidthLg = `calc(${semanticTokens.spacing2xl} * 20)`;
+
+const surfaceEnter = stylex.keyframes({
+  from: {opacity: 0, transform: 'translateY(4%)'},
+  to: {opacity: 1, transform: 'translateY(0)'},
+});
+
+const styles = stylex.create({
+  surface: {
+    animationDuration: semanticTokens.durationModerate,
+    animationName: {
+      default: surfaceEnter,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingEmphasized,
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationHigh,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    maxHeight: '100%',
+    // The sheet owns no padding of its own: the copy and the actions are two
+    // blocks divided by a rule, and a rule that stops short of the edge is a
+    // dash. Clipping here is what lets the corner radius survive both blocks.
+    overflow: 'hidden',
+    width: '100%',
+  },
+  sm: {maxWidth: surfaceWidthSm},
+  md: {maxWidth: surfaceWidthMd},
+  lg: {maxWidth: surfaceWidthLg},
+  body: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: semanticTokens.spacingSm,
+    minHeight: 0,
+    overflowY: 'auto',
+    padding: semanticTokens.spacingLg,
+  },
+  // The question is set in the display face at the section rank. A dialog
+  // asks one thing, and the mincho line is what separates the asking from the
+  // sentence underneath that explains what it costs.
+  title: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeLg,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingHeading,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+  },
+  description: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+  // The actions stand below the rule, on the tighter block padding a footer
+  // row takes everywhere else in the system.
+  footer: {
+    borderBlockStartColor: semanticTokens.borderDefault,
+    borderBlockStartStyle: semanticTokens.borderStyle,
+    borderBlockStartWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: semanticTokens.spacingSm,
+    justifyContent: 'flex-end',
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+  },
+});
+
+/** Widths a dialog surface can claim. */
+export type DialogSize = 'sm' | 'md' | 'lg';
+
+/** Props shared by modal dialog surfaces. */
+export interface DialogProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role' | 'title'
+> {
+  readonly children?: ReactNode;
+  readonly description?: ReactNode;
+  readonly dismissOnOutsideClick?: boolean;
+  readonly footer?: ReactNode;
+  readonly onDismiss?: () => void;
+  readonly open: boolean;
+  readonly size?: DialogSize;
+  readonly title: ReactNode;
+}
+
+/** @internal Shared modal surface for Dialog and AlertDialog. */
+export function DialogSurface({
+  children,
+  description,
+  dismissOnOutsideClick = true,
+  footer,
+  onDismiss,
+  open,
+  role,
+  size = 'md',
+  title,
+  ...props
+}: DialogProps & {readonly role: 'alertdialog' | 'dialog'}) {
+  const titleId = useId();
+  const descriptionId = useId();
+
+  return (
+    <Overlay
+      dismissOnOutsideClick={dismissOnOutsideClick}
+      {...(onDismiss ? {onDismiss} : {})}
+      open={open}
+    >
+      <div
+        {...props}
+        aria-describedby={description === undefined ? undefined : descriptionId}
+        aria-labelledby={titleId}
+        aria-modal="true"
+        role={role}
+        {...stylex.props(styles.surface, styles[size])}
+      >
+        <div {...stylex.props(styles.body, scrolling.region)}>
+          <h2 id={titleId} {...stylex.props(styles.title)}>
+            {title}
+          </h2>
+          {description === undefined ? null : (
+            <p id={descriptionId} {...stylex.props(styles.description)}>
+              {description}
+            </p>
+          )}
+          {children}
+        </div>
+        {footer === undefined ? null : (
+          <div {...stylex.props(styles.footer)}>{footer}</div>
+        )}
+      </div>
+    </Overlay>
+  );
+}
+
+/**
+ * Interrupts the page with a modal surface. Focus is trapped inside it, the
+ * page behind stops scrolling, and Escape closes it through `onDismiss`.
+ */
+export function Dialog(props: DialogProps) {
+  return <DialogSurface {...props} role="dialog" />;
+}

package/src/Dialog/index.ts

@@ -0,0 +1,6 @@
+export {
+  Dialog,
+  DialogSurface,
+  type DialogProps,
+  type DialogSize,
+} from './Dialog.js';

package/src/DropdownMenu/DropdownMenu.doc.ts

@@ -0,0 +1,41 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const dropdownMenuDoc = {
+  name: 'DropdownMenu',
+  description:
+    'Presents a keyboard-navigable list of actions beside a trigger.',
+  props: [
+    {name: 'alignment', description: 'Lines the menu up along the cross axis.'},
+    {
+      name: 'anchorRef',
+      description: 'References the trigger to anchor against.',
+    },
+    {name: 'children', description: 'Supplies the menu items.'},
+    {name: 'label', description: 'Names the menu for assistive technology.'},
+    {name: 'onDismiss', description: 'Runs on Escape or an outside click.'},
+    {name: 'open', description: 'Controls whether the menu renders.'},
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the trigger.',
+    },
+  ],
+  inheritedProps: ['None; DropdownMenu owns its menu element'],
+  example:
+    '<DropdownMenu anchorRef={triggerRef} label="Actions" onDismiss={close} open={open}>...</DropdownMenu>',
+  storyId: 'core-dropdown-menu--default',
+} satisfies ComponentDoc;
+
+export const dropdownMenuItemDoc = {
+  name: 'DropdownMenuItem',
+  description: 'Renders one action inside a DropdownMenu.',
+  props: [
+    {name: 'description', description: 'Adds secondary text under the label.'},
+    {name: 'leading', description: 'Places content before the label.'},
+    {name: 'trailing', description: 'Places content after the label.'},
+  ],
+  inheritedProps: [
+    'ButtonHTMLAttributes<HTMLButtonElement> except className and role',
+  ],
+  example: '<DropdownMenuItem onClick={publish}>Publish</DropdownMenuItem>',
+  storyId: 'core-dropdown-menu--default',
+} satisfies ComponentDoc;