@misoto22/kioku-ui 0.1.0 → 0.2.0

package/src/FileInput/FileInput.tsx

@@ -0,0 +1,186 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type ChangeEvent, type InputHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useInternationalization} from '../i18n/index.js';
+import {useFieldControl} from '../Field/index.js';
+
+const styles = stylex.create({
+  // The control and the name it reports are one field, so the gap between
+  // them belongs to this container rather than to a margin on either.
+  field: {display: 'grid', gap: semanticTokens.spacingXs},
+  // An input sinks below the card it sits on: a muted fill with a real
+  // hairline edge, never a shadow.
+  control: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    cursor: 'pointer',
+    display: 'block',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':disabled': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      borderColor: semanticTokens.borderDisabled,
+      color: semanticTokens.colorDisabledText,
+      cursor: 'default',
+    },
+    ':focus-visible': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':active:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.colorAccentActive,
+    },
+    ':hover:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.borderInteractive,
+    },
+    /*
+     * The native button, painted as the secondary `Button` it stands in for.
+     * It is the last piece of another system's chrome on the page, and hiding
+     * it behind a label is not the fix — that costs the control its keyboard
+     * behaviour and its platform file dialog. So it keeps the element and
+     * takes the paint: surface ground, a real hairline edge, the sheet's
+     * corner, and label type at the small control's height.
+     */
+    '::file-selector-button': {
+      backgroundColor: semanticTokens.colorSurface,
+      blockSize: semanticTokens.sizeControlSm,
+      borderColor: semanticTokens.borderStrong,
+      borderRadius: semanticTokens.radiusElement,
+      borderStyle: semanticTokens.borderStyle,
+      borderWidth: semanticTokens.borderWidth,
+      color: semanticTokens.colorText,
+      cursor: 'pointer',
+      fontFamily: semanticTokens.fontFamilyBody,
+      fontSize: semanticTokens.fontSizeSm,
+      fontWeight: semanticTokens.fontWeightMedium,
+      letterSpacing: semanticTokens.letterSpacingLabel,
+      lineHeight: semanticTokens.lineHeightBody,
+      marginInlineEnd: semanticTokens.spacingSm,
+      paddingInline: semanticTokens.spacingSm,
+      transitionDuration: semanticTokens.durationFast,
+      transitionProperty: 'background-color, border-color, color',
+      transitionTimingFunction: semanticTokens.easingStandard,
+      ':hover:not(:disabled)': {
+        backgroundColor: semanticTokens.colorOverlayHover,
+        borderColor: semanticTokens.borderInteractive,
+      },
+    },
+  },
+  /*
+   * The input's own `:disabled` block cannot reach the button — a pseudo-element
+   * only lives at the top of a style object — so the disabled paint is driven
+   * from React, the way `Slider` restates its engine-drawn parts. No hover to
+   * re-declare: the guard above compiles ahead of the pseudo-element, as
+   * `:hover:not(:disabled)::file-selector-button`, so it already tests the
+   * field rather than the button.
+   */
+  controlDisabled: {
+    '::file-selector-button': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      borderColor: semanticTokens.borderDisabled,
+      color: semanticTokens.colorDisabledText,
+      cursor: 'default',
+    },
+  },
+  invalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-visible': {borderColor: semanticTokens.statusDangerText},
+    ':active:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.statusDangerText,
+    },
+    ':hover:not(:disabled):not(:read-only):not(:focus-visible)': {
+      borderColor: semanticTokens.statusDangerText,
+    },
+  },
+  summary: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+});
+
+/** Props for choosing one or more files. */
+export interface FileInputProps extends Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'children' | 'className' | 'onChange' | 'type' | 'value'
+> {
+  readonly onFilesChange?: (files: readonly File[]) => void;
+}
+
+/**
+ * Chooses files through the native picker and names the current selection in
+ * text, because the file list itself is not announced by the control alone.
+ */
+export function FileInput({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  disabled,
+  id,
+  multiple,
+  onFilesChange,
+  required,
+  ...props
+}: FileInputProps) {
+  const field = useFieldControl();
+  const {messages} = useInternationalization();
+  const [names, setNames] = useState<readonly string[]>([]);
+  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 files = [...(event.currentTarget.files ?? [])];
+    setNames(files.map((file) => file.name));
+    onFilesChange?.(files);
+  }
+
+  return (
+    <div {...stylex.props(styles.field)}>
+      <input
+        {...props}
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        multiple={multiple}
+        onChange={handleChange}
+        required={required ?? field?.required}
+        {...stylex.props(
+          styles.control,
+          disabled ? styles.controlDisabled : undefined,
+          invalid && !disabled ? styles.invalid : undefined,
+        )}
+        type="file"
+      />
+      <p aria-live="polite" role="status" {...stylex.props(styles.summary)}>
+        {names.length === 0 ? messages.fileInputEmpty : names.join(', ')}
+      </p>
+    </div>
+  );
+}

package/src/FileInput/index.ts

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

package/src/FormLayout/FormLayout.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const formLayoutDoc = {
+  name: 'FormLayout',
+  description: 'Arranges fields and their submit actions.',
+  props: [
+    {
+      name: 'actions',
+      description: 'Places submit actions across the full width.',
+    },
+    {name: 'children', description: 'Supplies the fields.'},
+    {name: 'columns', description: 'Selects one or two responsive columns.'},
+  ],
+  inheritedProps: [
+    'FormHTMLAttributes<HTMLFormElement> except children and className',
+  ],
+  example:
+    '<FormLayout actions={<Button>Save</Button>} columns={2}>…</FormLayout>',
+  storyId: 'core-form-layout--default',
+} satisfies ComponentDoc;

package/src/FormLayout/FormLayout.tsx

@@ -0,0 +1,69 @@
+import * as stylex from '@stylexjs/stylex';
+import type {FormHTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// The narrowest a labelled field stays readable at before two columns should
+// collapse into one. The spacing scale has no single step that measures it.
+const columnMinimumWidth = `calc(${semanticTokens.spacing2xl} * 8)`;
+
+const styles = stylex.create({
+  form: {
+    // Fields sit a medium step apart down the page and a large one across it,
+    // so a two-column form reads as columns rather than as a mesh.
+    columnGap: semanticTokens.spacingLg,
+    display: 'grid',
+    fontFamily: semanticTokens.fontFamilyBody,
+    rowGap: semanticTokens.spacingMd,
+  },
+  single: {gridTemplateColumns: '1fr'},
+  double: {
+    gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${columnMinimumWidth}), 1fr))`,
+  },
+  actions: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: semanticTokens.spacingSm,
+    gridColumn: '1 / -1',
+    justifyContent: 'flex-end',
+  },
+});
+
+/** Column counts a form can lay its fields out in. */
+export type FormColumns = 1 | 2;
+
+/** Props for the grid that arranges fields and their actions. */
+export interface FormLayoutProps extends Omit<
+  FormHTMLAttributes<HTMLFormElement>,
+  'children' | 'className'
+> {
+  readonly actions?: ReactNode;
+  readonly children: ReactNode;
+  readonly columns?: FormColumns;
+}
+
+/**
+ * Arranges fields and their submit actions. Two columns collapse to one when
+ * the container is narrow, so a form never forces sideways scrolling.
+ */
+export function FormLayout({
+  actions,
+  children,
+  columns = 1,
+  ...props
+}: FormLayoutProps) {
+  return (
+    <form
+      {...props}
+      {...stylex.props(
+        styles.form,
+        columns === 1 ? styles.single : styles.double,
+      )}
+    >
+      {children}
+      {actions === undefined ? null : (
+        <div {...stylex.props(styles.actions)}>{actions}</div>
+      )}
+    </form>
+  );
+}

package/src/FormLayout/index.ts

@@ -0,0 +1,5 @@
+export {
+  FormLayout,
+  type FormColumns,
+  type FormLayoutProps,
+} from './FormLayout.js';

package/src/HStack/HStack.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const hStackDoc = {
+  name: 'HStack',
+  description: 'Arranges children in an evenly spaced row.',
+  props: [
+    {name: 'align', description: 'Places children along the cross axis.'},
+    {name: 'gap', description: 'Selects the space between children.'},
+    {name: 'justify', description: 'Distributes children along the row.'},
+    {name: 'wrap', description: 'Allows children to flow onto more rows.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLDivElement> except className'],
+  example: '<HStack gap="sm" justify="between">…</HStack>',
+  storyId: 'core-h-stack--default',
+} satisfies ComponentDoc;

package/src/HStack/HStack.tsx

@@ -0,0 +1,91 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {Space} from '../Stack/index.js';
+
+const styles = stylex.create({
+  base: {display: 'flex', flexDirection: 'row'},
+  wrap: {flexWrap: 'wrap'},
+  gapXs: {gap: semanticTokens.spacingXs},
+  gapSm: {gap: semanticTokens.spacingSm},
+  gapMd: {gap: semanticTokens.spacingMd},
+  gapLg: {gap: semanticTokens.spacingLg},
+  gapXl: {gap: semanticTokens.spacingXl},
+  gap2xl: {gap: semanticTokens.spacing2xl},
+  alignStretch: {alignItems: 'stretch'},
+  alignStart: {alignItems: 'flex-start'},
+  alignCenter: {alignItems: 'center'},
+  alignEnd: {alignItems: 'flex-end'},
+  alignBaseline: {alignItems: 'baseline'},
+  justifyStart: {justifyContent: 'flex-start'},
+  justifyCenter: {justifyContent: 'center'},
+  justifyEnd: {justifyContent: 'flex-end'},
+  justifyBetween: {justifyContent: 'space-between'},
+});
+
+const gaps = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+} as const;
+
+const aligns = {
+  stretch: styles.alignStretch,
+  start: styles.alignStart,
+  center: styles.alignCenter,
+  end: styles.alignEnd,
+  baseline: styles.alignBaseline,
+} as const;
+
+const justifies = {
+  start: styles.justifyStart,
+  center: styles.justifyCenter,
+  end: styles.justifyEnd,
+  between: styles.justifyBetween,
+} as const;
+
+/** Cross-axis placement a horizontal stack can apply. */
+export type HStackAlign = 'baseline' | 'center' | 'end' | 'start' | 'stretch';
+
+/** Main-axis distribution a horizontal stack can apply. */
+export type HStackJustify = 'between' | 'center' | 'end' | 'start';
+
+/** Props for a row of evenly spaced children. */
+export interface HStackProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly align?: HStackAlign;
+  readonly gap?: Space;
+  readonly justify?: HStackJustify;
+  readonly wrap?: boolean;
+}
+
+/** Arranges children in a row. Use `Stack` for the vertical equivalent. */
+export function HStack({
+  align = 'center',
+  children,
+  gap = 'md',
+  justify = 'start',
+  wrap = false,
+  ...props
+}: HStackProps) {
+  return (
+    <div
+      {...props}
+      {...stylex.props(
+        styles.base,
+        gaps[gap],
+        aligns[align],
+        justifies[justify],
+        wrap && styles.wrap,
+      )}
+    >
+      {children}
+    </div>
+  );
+}

package/src/HStack/index.ts

@@ -0,0 +1,6 @@
+export {
+  HStack,
+  type HStackAlign,
+  type HStackJustify,
+  type HStackProps,
+} from './HStack.js';

package/src/Heading/Heading.tsx

@@ -4,16 +4,29 @@ import {createElement, type HTMLAttributes} from 'react';
 import {semanticTokens} from '../authoring.stylex.js';
 
 const styles = stylex.create({
+  // Medium, not strong. A heading on this paper is separated from the copy by
+  // size, tracking and the face it is cut in; adding weight on top of all
+  // three makes it shout, and the display face has no bold worth synthesising
+  // anyway. Every title in the console is set at the medium weight.
   base: {
     color: semanticTokens.colorText,
     fontFamily: semanticTokens.fontFamilyHeading,
-    fontWeight: semanticTokens.fontWeightStrong,
+    fontWeight: semanticTokens.fontWeightMedium,
     lineHeight: semanticTokens.lineHeightHeading,
     margin: 0,
   },
-  page: {fontSize: semanticTokens.fontSize2xl},
-  section: {fontSize: semanticTokens.fontSizeXl},
-  subsection: {fontSize: semanticTokens.fontSizeLg},
+  page: {
+    fontSize: semanticTokens.fontSize2xl,
+    letterSpacing: semanticTokens.letterSpacingTitle,
+  },
+  section: {
+    fontSize: semanticTokens.fontSizeXl,
+    letterSpacing: semanticTokens.letterSpacingTitle,
+  },
+  subsection: {
+    fontSize: semanticTokens.fontSizeLg,
+    letterSpacing: semanticTokens.letterSpacingHeading,
+  },
   interface: {fontFamily: semanticTokens.fontFamilyHeading},
   display: {
     fontFamily: semanticTokens.fontFamilyDisplay,

package/src/HoverCard/HoverCard.doc.ts

@@ -0,0 +1,31 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const hoverCardDoc = {
+  name: 'HoverCard',
+  description: 'Previews interactive detail on hover and on focus.',
+  props: [
+    {name: 'alignment', description: 'Lines the card up along the cross axis.'},
+    {name: 'children', description: 'Supplies the single trigger element.'},
+    {
+      name: 'closeDelay',
+      description: 'Delays closing after the pointer leaves.',
+    },
+    {name: 'content', description: 'Supplies the preview content.'},
+    {
+      name: 'label',
+      description: 'Names the interactive surface for assistive technology.',
+    },
+    {
+      name: 'openDelay',
+      description: 'Delays opening after the pointer arrives.',
+    },
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the trigger.',
+    },
+  ],
+  inheritedProps: ['None; HoverCard renders only its trigger and preview'],
+  example:
+    '<HoverCard content={<Profile />}><Link href="/a">Ada</Link></HoverCard>',
+  storyId: 'core-hover-card--default',
+} satisfies ComponentDoc;

package/src/HoverCard/HoverCard.tsx

@@ -0,0 +1,121 @@
+import {
+  Children,
+  cloneElement,
+  useEffect,
+  useRef,
+  useState,
+  type FocusEvent,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import type {Alignment, Placement} from '../hooks/useAnchoredPosition.js';
+import {Popover} from '../Popover/index.js';
+
+interface TriggerProps {
+  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 rich preview shown on hover and on focus. */
+export interface HoverCardProps {
+  readonly alignment?: Alignment;
+  readonly children: ReactElement<TriggerProps>;
+  readonly closeDelay?: number;
+  readonly content: ReactNode;
+  /**
+   * Names the surface. The content is interactive, so it is announced as a
+   * dialog, and a dialog with no name is one an assistive technology can enter
+   * but not describe. Required for that reason rather than for styling.
+   */
+  readonly label: string;
+  readonly openDelay?: number;
+  readonly placement?: Placement;
+}
+
+/**
+ * Previews related detail beside its trigger. Unlike Tooltip the content is
+ * interactive and stays open while the pointer is inside it, so it can hold
+ * links and actions.
+ */
+export function HoverCard({
+  alignment,
+  children,
+  closeDelay = 150,
+  content,
+  label,
+  openDelay = 300,
+  placement = 'bottom',
+}: HoverCardProps) {
+  const anchorRef = useRef<HTMLElement>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const [open, setOpen] = useState(false);
+
+  useEffect(
+    () => () => {
+      clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  function scheduleOpen() {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      setOpen(true);
+    }, openDelay);
+  }
+
+  function scheduleClose() {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      setOpen(false);
+    }, closeDelay);
+  }
+
+  const trigger = Children.only(children);
+  const anchor = cloneElement(trigger, {
+    onBlur: (event: FocusEvent<HTMLElement>) => {
+      trigger.props.onBlur?.(event);
+      scheduleClose();
+    },
+    onFocus: (event: FocusEvent<HTMLElement>) => {
+      trigger.props.onFocus?.(event);
+      scheduleOpen();
+    },
+    onMouseEnter: (event: MouseEvent<HTMLElement>) => {
+      trigger.props.onMouseEnter?.(event);
+      scheduleOpen();
+    },
+    onMouseLeave: (event: MouseEvent<HTMLElement>) => {
+      trigger.props.onMouseLeave?.(event);
+      scheduleClose();
+    },
+    ref: anchorRef,
+  });
+
+  return (
+    <>
+      {anchor}
+      <Popover
+        {...(alignment ? {alignment} : {})}
+        anchorRef={anchorRef}
+        aria-label={label}
+        onDismiss={() => {
+          setOpen(false);
+        }}
+        onMouseEnter={() => {
+          clearTimeout(timer.current);
+        }}
+        onMouseLeave={scheduleClose}
+        open={open}
+        placement={placement}
+      >
+        {content}
+      </Popover>
+    </>
+  );
+}

package/src/HoverCard/index.ts

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

package/src/Icon/Icon.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const iconDoc = {
+  name: 'Icon',
+  description: 'Sizes and colours caller-supplied SVG paths.',
+  props: [
+    {
+      name: 'label',
+      description:
+        'Names the icon for assistive technology; omit when decorative.',
+    },
+    {name: 'size', description: 'Selects the square size from the type scale.'},
+    {name: 'tone', description: 'Selects a semantic colour role.'},
+  ],
+  inheritedProps: [
+    'SVGAttributes<SVGSVGElement> except aria-hidden, aria-label, className, role',
+  ],
+  example:
+    '<Icon label="Search"><path d="M10 2a8 8 0 1 0 0 16 8 8 0 0 0 0-16Z" /></Icon>',
+  storyId: 'core-icon--default',
+} satisfies ComponentDoc;