@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Text/Text.tsx

@@ -8,6 +8,7 @@ const styles = stylex.create({
     color: semanticTokens.colorText,
     fontFamily: semanticTokens.fontFamilyBody,
     fontWeight: semanticTokens.fontWeightRegular,
+    letterSpacing: semanticTokens.letterSpacingBody,
     lineHeight: semanticTokens.lineHeightBody,
     margin: 0,
   },

package/src/TextArea/TextArea.tsx

@@ -4,21 +4,37 @@ import type {ChangeEvent, TextareaHTMLAttributes} from 'react';
 import {semanticTokens} from '../authoring.stylex.js';
 import {useFieldControl} from '../Field/index.js';
 
+// Four lines of body copy plus the control's own block padding. Written as the
+// relationship rather than as a length, so the field still opens on four lines
+// when density or type size moves under it.
+const minimumHeight = `calc(4 * ${semanticTokens.fontSizeMd} * ${semanticTokens.lineHeightBody} + 2 * ${semanticTokens.spacingXs})`;
+
 const controlStyles = stylex.create({
   base: {
-    backgroundColor: semanticTokens.colorSurface,
+    backgroundColor: semanticTokens.colorSurfaceMuted,
     boxSizing: 'border-box',
-    borderColor: semanticTokens.borderDefault,
+    borderColor: semanticTokens.borderStrong,
     borderRadius: semanticTokens.radiusElement,
     borderStyle: semanticTokens.borderStyle,
     borderWidth: semanticTokens.borderWidth,
     color: semanticTokens.colorText,
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
     lineHeight: semanticTokens.lineHeightBody,
-    minHeight: '96px',
+    minHeight: minimumHeight,
+    // Vertical only. The UA default lets a reader drag the field wider than
+    // the column it sits in, taking the form's layout with it; height is the
+    // axis they actually want.
+    resize: 'vertical',
     paddingBlock: semanticTokens.spacingXs,
     paddingInline: semanticTokens.spacingSm,
+    // The three longhands every other well in the system declares, so an edge
+    // that changes on hover or focus moves at the same speed as the ones
+    // beside it instead of snapping.
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
     '::placeholder': {color: semanticTokens.colorTextMuted},
     ':disabled': {
       backgroundColor: semanticTokens.colorDisabledSurface,
@@ -40,7 +56,8 @@ const controlStyles = stylex.create({
     },
   },
   readOnly: {
-    backgroundColor: semanticTokens.colorSurfaceMuted,
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
     color: semanticTokens.colorText,
   },
   invalid: {

package/src/TextInput/TextInput.tsx

@@ -6,19 +6,26 @@ import {useFieldControl} from '../Field/index.js';
 
 const controlStyles = stylex.create({
   base: {
-    backgroundColor: semanticTokens.colorSurface,
+    backgroundColor: semanticTokens.colorSurfaceMuted,
     boxSizing: 'border-box',
-    borderColor: semanticTokens.borderDefault,
+    borderColor: semanticTokens.borderStrong,
     borderRadius: semanticTokens.radiusElement,
     borderStyle: semanticTokens.borderStyle,
     borderWidth: semanticTokens.borderWidth,
     color: semanticTokens.colorText,
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
     height: semanticTokens.sizeControlMd,
     lineHeight: semanticTokens.lineHeightBody,
     paddingBlock: semanticTokens.spacingXs,
     paddingInline: semanticTokens.spacingSm,
+    // The three longhands every other well in the system declares, so an edge
+    // that changes on hover or focus moves at the same speed as the ones
+    // beside it instead of snapping.
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
     '::placeholder': {color: semanticTokens.colorTextMuted},
     ':disabled': {
       backgroundColor: semanticTokens.colorDisabledSurface,
@@ -40,7 +47,8 @@ const controlStyles = stylex.create({
     },
   },
   readOnly: {
-    backgroundColor: semanticTokens.colorSurfaceMuted,
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
     color: semanticTokens.colorText,
   },
   invalid: {

package/src/Thumbnail/Thumbnail.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const thumbnailDoc = {
+  name: 'Thumbnail',
+  description: 'Shows a small bounded preview that degrades to text.',
+  props: [
+    {name: 'alt', description: 'Describes the image for assistive technology.'},
+    {
+      name: 'fallback',
+      description: 'Replaces the alt text when loading fails.',
+    },
+    {name: 'size', description: 'Selects the square size.'},
+    {name: 'src', description: 'Points at the image to show.'},
+  ],
+  inheritedProps: [
+    'ImgHTMLAttributes<HTMLImageElement> except children, className, height, and width',
+  ],
+  example: '<Thumbnail alt="Release cover" src="/cover.png" />',
+  storyId: 'core-thumbnail--default',
+} satisfies ComponentDoc;

package/src/Thumbnail/Thumbnail.tsx

@@ -0,0 +1,94 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type ImgHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// A preview is measured in control heights so the ladder stays a ladder:
+// one control tall, two, three. The spacing scale bends with density; a
+// picture box must not.
+const previewMedium = `calc(2 * ${semanticTokens.sizeControlLg})`;
+const previewLarge = `calc(3 * ${semanticTokens.sizeControlLg})`;
+
+const styles = stylex.create({
+  frame: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderDefault,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    display: 'inline-flex',
+    flexShrink: 0,
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  sm: {
+    height: semanticTokens.sizeControlLg,
+    width: semanticTokens.sizeControlLg,
+  },
+  md: {height: previewMedium, width: previewMedium},
+  lg: {height: previewLarge, width: previewLarge},
+  image: {
+    display: 'block',
+    height: '100%',
+    objectFit: 'cover',
+    width: '100%',
+  },
+  // The label of last resort, so it is set as one: the eyebrow recipe exactly
+  // — smallest size, opened right up, heading face, a rank below the frame.
+  fallback: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightBody,
+    padding: semanticTokens.spacingXs,
+    textAlign: 'center',
+  },
+});
+
+/** Sizes a thumbnail can occupy. */
+export type ThumbnailSize = 'sm' | 'md' | 'lg';
+
+/** Props for a small bounded preview image. */
+export interface ThumbnailProps extends Omit<
+  ImgHTMLAttributes<HTMLImageElement>,
+  'children' | 'className' | 'height' | 'width'
+> {
+  readonly alt: string;
+  readonly fallback?: string;
+  readonly size?: ThumbnailSize;
+  readonly src: string;
+}
+
+/**
+ * Shows a small bounded preview. A failed image degrades to text rather than
+ * a broken-image glyph, because the alternative text is the content.
+ */
+export function Thumbnail({
+  alt,
+  fallback,
+  size = 'md',
+  src,
+  ...props
+}: ThumbnailProps) {
+  const [failed, setFailed] = useState(false);
+
+  return (
+    <span {...stylex.props(styles.frame, styles[size])}>
+      {failed ? (
+        <span {...stylex.props(styles.fallback)}>{fallback ?? alt}</span>
+      ) : (
+        <img
+          {...props}
+          alt={alt}
+          onError={() => {
+            setFailed(true);
+          }}
+          src={src}
+          {...stylex.props(styles.image)}
+        />
+      )}
+    </span>
+  );
+}

package/src/Thumbnail/index.ts

@@ -0,0 +1,5 @@
+export {
+  Thumbnail,
+  type ThumbnailProps,
+  type ThumbnailSize,
+} from './Thumbnail.js';

package/src/TimeInput/TimeInput.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const timeInputDoc = {
+  name: 'TimeInput',
+  description: 'Accepts one time of day 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: '<TimeInput onValueChange={setValue} value={value} />',
+  storyId: 'core-time-input--default',
+} satisfies ComponentDoc;

package/src/TimeInput/TimeInput.tsx

@@ -0,0 +1,9 @@
+import {TemporalInput, type TemporalInputProps} from '../DateInput/index.js';
+
+/** Props for a time field. */
+export type TimeInputProps = TemporalInputProps;
+
+/** Accepts one time of day, exchanged as an ISO `HH:MM` string. */
+export function TimeInput(props: TimeInputProps) {
+  return <TemporalInput {...props} type="time" />;
+}

package/src/TimeInput/index.ts

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

package/src/Timestamp/Timestamp.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const timestampDoc = {
+  name: 'Timestamp',
+  description: 'Shows a point in time with its machine-readable value.',
+  props: [
+    {name: 'format', description: 'Builds the text a reader sees.'},
+    {name: 'value', description: 'Supplies the date to show.'},
+  ],
+  inheritedProps: [
+    'TimeHTMLAttributes<HTMLTimeElement> except children, className, and dateTime',
+  ],
+  example: '<Timestamp value="2026-08-18T09:30:00Z" />',
+  storyId: 'core-timestamp--default',
+} satisfies ComponentDoc;

package/src/Timestamp/Timestamp.tsx

@@ -0,0 +1,52 @@
+import * as stylex from '@stylexjs/stylex';
+import type {TimeHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  // A date is a figure, and figures are set in the mono face: tabular so a
+  // column of them lines up, and tightened because mono is already too wide.
+  time: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+});
+
+/** Props for a machine-readable point in time. */
+export interface TimestampProps extends Omit<
+  TimeHTMLAttributes<HTMLTimeElement>,
+  'children' | 'className' | 'dateTime'
+> {
+  readonly format?: (value: Date) => string;
+  readonly value: Date | string;
+}
+
+const defaultFormat = (value: Date) =>
+  value.toLocaleString(undefined, {dateStyle: 'medium', timeStyle: 'short'});
+
+/**
+ * Shows a point in time with its machine-readable value attached, so the date
+ * a reader sees and the one a parser reads cannot drift apart.
+ */
+export function Timestamp({
+  format = defaultFormat,
+  value,
+  ...props
+}: TimestampProps) {
+  const date = typeof value === 'string' ? new Date(value) : value;
+  const valid = !Number.isNaN(date.getTime());
+
+  return (
+    <time
+      {...props}
+      {...(valid ? {dateTime: date.toISOString()} : {})}
+      {...stylex.props(styles.time)}
+    >
+      {valid ? format(date) : String(value)}
+    </time>
+  );
+}

package/src/Timestamp/index.ts

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

package/src/Toast/Toast.doc.ts

@@ -0,0 +1,35 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const toastDoc = {
+  name: 'Toast',
+  description: 'Renders one transient notification.',
+  props: [
+    {
+      name: 'action',
+      description: 'Places a follow-up action in the notification.',
+    },
+    {name: 'description', description: 'Adds detail under the title.'},
+    {name: 'title', description: 'States what happened.'},
+    {name: 'tone', description: 'Selects a semantic status colour.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, role, and title',
+  ],
+  example: '<Toast title="Draft saved" tone="success" />',
+  storyId: 'core-toast--default',
+} satisfies ComponentDoc;
+
+export const toastProviderDoc = {
+  name: 'ToastProvider',
+  description: 'Hosts the notification queue and its live region.',
+  props: [
+    {name: 'children', description: 'Supplies the tree that can raise toasts.'},
+    {
+      name: 'label',
+      description: 'Names the live region for assistive technology.',
+    },
+  ],
+  inheritedProps: ['None; ToastProvider owns its live region'],
+  example: '<ToastProvider>{app}</ToastProvider>',
+  storyId: 'core-toast-provider--default',
+} satisfies ComponentDoc;

package/src/Toast/Toast.tsx

@@ -0,0 +1,271 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {StatusTone} from '../Badge/index.js';
+import {Layer} from '../Layer/index.js';
+
+// A toast is a floating surface, so its width is set in spacing steps rather
+// than in a literal the token contract cannot theme.
+const regionWidth = `calc(16 * ${semanticTokens.spacingXl})`;
+
+// The dot that names the tone. Two of the smallest spacing step: any larger
+// and it stops being a mark on the slip and starts being a bullet.
+const dotSize = `calc(2 * ${semanticTokens.spacingXs})`;
+
+// Notifications arrive from the edge they are anchored to.
+const enter = stylex.keyframes({
+  from: {opacity: 0, transform: 'translateY(25%)'},
+  to: {opacity: 1, transform: 'translateY(0)'},
+});
+
+const styles = stylex.create({
+  region: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: semanticTokens.spacingSm,
+    insetBlockEnd: 0,
+    insetInlineEnd: 0,
+    maxWidth: regionWidth,
+    padding: semanticTokens.spacingLg,
+    pointerEvents: 'none',
+    position: 'fixed',
+    width: '100%',
+  },
+  // A slip of the same paper as everything else, laid on the stack. Dyeing the
+  // whole slip to carry the tone made four differently coloured cards; the
+  // tone is one dot, and the slip stays paper so a stack of them reads as a
+  // stack rather than as a paint chart.
+  toast: {
+    alignItems: 'center',
+    animationDuration: semanticTokens.durationModerate,
+    animationName: {
+      default: enter,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingEmphasized,
+    backgroundColor: semanticTokens.colorSurface,
+    borderRadius: semanticTokens.radiusContainer,
+    // A floating surface carries elevation instead of an edge; stacking both
+    // would draw the same line twice.
+    borderStyle: 'none',
+    boxShadow: semanticTokens.elevationMedium,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingMd,
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+    pointerEvents: 'auto',
+  },
+  // The one round shape the system allows outside a knob.
+  dot: {
+    blockSize: dotSize,
+    borderRadius: semanticTokens.radiusFull,
+    flexShrink: 0,
+    inlineSize: dotSize,
+  },
+  info: {backgroundColor: semanticTokens.statusInfoText},
+  success: {backgroundColor: semanticTokens.statusSuccessText},
+  warning: {backgroundColor: semanticTokens.statusWarningText},
+  danger: {backgroundColor: semanticTokens.statusDangerText},
+  message: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexGrow: 1,
+    gap: semanticTokens.spacingXs,
+    minWidth: 0,
+  },
+  // Two ranks of ink instead of two faces. A notification is one line long
+  // often enough that a heading face on top of it reads as a headline.
+  title: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+  description: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+  action: {
+    alignItems: 'center',
+    display: 'flex',
+    flexShrink: 0,
+    gap: semanticTokens.spacingSm,
+  },
+});
+
+/** Props for one notification surface. */
+export interface ToastProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role' | 'title'
+> {
+  readonly action?: ReactNode;
+  readonly description?: ReactNode;
+  readonly title: ReactNode;
+  readonly tone?: StatusTone;
+}
+
+/** Renders one notification. Use `useToast` rather than placing these by hand. */
+export function Toast({
+  action,
+  description,
+  title,
+  tone = 'info',
+  ...props
+}: ToastProps) {
+  const isDanger = tone === 'danger';
+
+  return (
+    <div
+      {...props}
+      aria-live={isDanger ? 'assertive' : 'polite'}
+      role={isDanger ? 'alert' : 'status'}
+      {...stylex.props(styles.toast)}
+    >
+      <span aria-hidden="true" {...stylex.props(styles.dot, styles[tone])} />
+      <div {...stylex.props(styles.message)}>
+        <p {...stylex.props(styles.title)}>{title}</p>
+        {description === undefined ? null : (
+          <p {...stylex.props(styles.description)}>{description}</p>
+        )}
+      </div>
+      {action === undefined ? null : (
+        <div {...stylex.props(styles.action)}>{action}</div>
+      )}
+    </div>
+  );
+}
+
+/** A notification request handed to `useToast().show`. */
+export interface ToastOptions {
+  readonly action?: ReactNode;
+  readonly description?: ReactNode;
+  readonly duration?: number;
+  readonly title: ReactNode;
+  readonly tone?: StatusTone;
+}
+
+interface ToastRecord extends ToastOptions {
+  readonly id: string;
+}
+
+/** The notification queue exposed to descendants. */
+export interface ToastContextValue {
+  readonly dismiss: (id: string) => void;
+  readonly show: (toast: ToastOptions) => string;
+}
+
+const ToastContext = createContext<ToastContextValue | undefined>(undefined);
+
+/** Props for the notification queue host. */
+export interface ToastProviderProps {
+  readonly children: ReactNode;
+  readonly label?: string;
+}
+
+/**
+ * Hosts the notification queue and its live region. Place one near the root of
+ * a host application; notifications are requested through `useToast`.
+ */
+export function ToastProvider({
+  children,
+  label = 'Notifications',
+}: ToastProviderProps) {
+  const [toasts, setToasts] = useState<readonly ToastRecord[]>([]);
+  const nextId = useRef(0);
+  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());
+
+  const dismiss = useCallback((id: string) => {
+    const timer = timers.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timers.current.delete(id);
+    }
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, []);
+
+  const show = useCallback(
+    (toast: ToastOptions) => {
+      nextId.current += 1;
+      const id = `toast-${nextId.current}`;
+      setToasts((current) => [...current, {...toast, id}]);
+
+      const duration = toast.duration ?? 5000;
+      if (duration > 0) {
+        timers.current.set(
+          id,
+          setTimeout(() => {
+            dismiss(id);
+          }, duration),
+        );
+      }
+
+      return id;
+    },
+    [dismiss],
+  );
+
+  const pending = timers.current;
+  useEffect(
+    () => () => {
+      for (const timer of pending.values()) {
+        clearTimeout(timer);
+      }
+      pending.clear();
+    },
+    [pending],
+  );
+
+  const value = useMemo(() => ({dismiss, show}), [dismiss, show]);
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <Layer>
+        <div
+          aria-label={label}
+          aria-live="polite"
+          role="region"
+          {...stylex.props(styles.region)}
+        >
+          {toasts.map((toast) => (
+            <Toast
+              action={toast.action}
+              description={toast.description}
+              key={toast.id}
+              title={toast.title}
+              tone={toast.tone}
+            />
+          ))}
+        </div>
+      </Layer>
+    </ToastContext.Provider>
+  );
+}
+
+/** Reads the notification queue. Throws when no `ToastProvider` is above it. */
+export function useToast(): ToastContextValue {
+  const value = useContext(ToastContext);
+  if (!value) {
+    throw new Error('useToast must be used within a ToastProvider.');
+  }
+  return value;
+}

package/src/Toast/index.ts

@@ -0,0 +1,9 @@
+export {
+  Toast,
+  ToastProvider,
+  useToast,
+  type ToastContextValue,
+  type ToastOptions,
+  type ToastProps,
+  type ToastProviderProps,
+} from './Toast.js';