@misoto22/kioku-ui 0.0.0

package/src/SegmentedControl/SegmentedControl.tsx

@@ -0,0 +1,238 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  root: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusElement,
+    display: 'inline-flex',
+    gap: semanticTokens.spacingXs,
+    padding: semanticTokens.spacingXs,
+  },
+  option: {
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusInner,
+    borderStyle: 'none',
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    ':disabled': {color: semanticTokens.colorDisabledText},
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  unselected: {
+    ':active:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayActive,
+    },
+    ':hover:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+    },
+  },
+  selected: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    boxShadow: semanticTokens.elevationLow,
+    color: semanticTokens.colorText,
+  },
+  vertical: {flexDirection: 'column'},
+});
+
+export interface SegmentedControlOption<Value extends string = string> {
+  readonly disabled?: boolean;
+  readonly label: ReactNode;
+  readonly value: Value;
+}
+
+type SharedSegmentedControlProps<Value extends string> = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'aria-labelledby' | 'className' | 'defaultValue' | 'onChange'
+> & {
+  readonly disabled?: boolean;
+  readonly onValueChange?: (value: Value) => void;
+  readonly options: readonly SegmentedControlOption<Value>[];
+  readonly orientation?: 'horizontal' | 'vertical';
+};
+
+type SegmentedControlAccessibleName =
+  | {
+      readonly 'aria-label': string;
+      readonly 'aria-labelledby'?: string;
+    }
+  | {
+      readonly 'aria-label'?: string;
+      readonly 'aria-labelledby': string;
+    };
+
+type ControlledSegmentedControlProps<Value extends string> =
+  SharedSegmentedControlProps<Value> & {
+    readonly defaultValue?: never;
+    readonly onValueChange: (value: Value) => void;
+    readonly value: Value;
+  };
+
+type UncontrolledSegmentedControlProps<Value extends string> =
+  SharedSegmentedControlProps<Value> & {
+    readonly defaultValue?: Value;
+    readonly value?: never;
+  };
+
+export type SegmentedControlProps<Value extends string = string> = (
+  | ControlledSegmentedControlProps<Value>
+  | UncontrolledSegmentedControlProps<Value>
+) &
+  SegmentedControlAccessibleName;
+
+export function SegmentedControl<Value extends string = string>({
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  defaultValue,
+  disabled = false,
+  onValueChange,
+  options,
+  orientation = 'horizontal',
+  value,
+  ...props
+}: SegmentedControlProps<Value>) {
+  if (!ariaLabel?.trim() && !ariaLabelledBy?.trim()) {
+    throw new Error('SegmentedControl requires an accessible name');
+  }
+
+  const firstEnabledValue = options.find((option) => !option.disabled)?.value;
+  const [internalValue, setInternalValue] = useState<Value | undefined>(
+    defaultValue ?? firstEnabledValue,
+  );
+  const requestedValue = value ?? internalValue;
+  const selectedValue = options.some(
+    (option) => option.value === requestedValue && !option.disabled,
+  )
+    ? requestedValue
+    : firstEnabledValue;
+  const optionRefs = useRef(new Map<Value, HTMLButtonElement>());
+  const enabledOptions = options.filter(
+    (option) => !disabled && !option.disabled,
+  );
+
+  function select(nextValue: Value) {
+    if (value === undefined) {
+      setInternalValue(nextValue);
+    }
+    onValueChange?.(nextValue);
+  }
+
+  function moveSelection(
+    currentValue: Value,
+    direction: 'first' | 'last' | 'next' | 'previous',
+  ) {
+    if (enabledOptions.length === 0) {
+      return;
+    }
+
+    const currentIndex = enabledOptions.findIndex(
+      (option) => option.value === currentValue,
+    );
+    let nextIndex: number;
+
+    if (direction === 'first') {
+      nextIndex = 0;
+    } else if (direction === 'last') {
+      nextIndex = enabledOptions.length - 1;
+    } else if (direction === 'next') {
+      nextIndex =
+        (currentIndex + 1 + enabledOptions.length) % enabledOptions.length;
+    } else {
+      nextIndex =
+        (currentIndex - 1 + enabledOptions.length) % enabledOptions.length;
+    }
+
+    const nextOption = enabledOptions[nextIndex];
+    if (!nextOption) {
+      return;
+    }
+    select(nextOption.value);
+    optionRefs.current.get(nextOption.value)?.focus();
+  }
+
+  function handleKeyDown(
+    event: KeyboardEvent<HTMLButtonElement>,
+    currentValue: Value,
+  ) {
+    const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+    const previousKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+    const direction =
+      event.key === nextKey
+        ? 'next'
+        : event.key === previousKey
+          ? 'previous'
+          : event.key === 'Home'
+            ? 'first'
+            : event.key === 'End'
+              ? 'last'
+              : undefined;
+
+    if (direction) {
+      event.preventDefault();
+      moveSelection(currentValue, direction);
+    }
+  }
+
+  return (
+    <div
+      {...props}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-disabled={disabled || undefined}
+      aria-orientation={orientation}
+      role="radiogroup"
+      {...stylex.props(
+        styles.root,
+        orientation === 'vertical' ? styles.vertical : undefined,
+      )}
+    >
+      {options.map((option) => {
+        const isDisabled = disabled || Boolean(option.disabled);
+        const isSelected = option.value === selectedValue;
+
+        return (
+          <button
+            aria-checked={isSelected}
+            disabled={isDisabled}
+            key={option.value}
+            onClick={() => select(option.value)}
+            onKeyDown={(event) => handleKeyDown(event, option.value)}
+            ref={(element) => {
+              if (element) {
+                optionRefs.current.set(option.value, element);
+              } else {
+                optionRefs.current.delete(option.value);
+              }
+            }}
+            role="radio"
+            tabIndex={isSelected && !isDisabled ? 0 : -1}
+            {...stylex.props(
+              styles.option,
+              isSelected ? styles.selected : styles.unselected,
+            )}
+            type="button"
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/SegmentedControl/index.ts

@@ -0,0 +1,5 @@
+export {
+  SegmentedControl,
+  type SegmentedControlOption,
+  type SegmentedControlProps,
+} from './SegmentedControl.js';

package/src/Skeleton/Skeleton.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const skeletonDoc = {
+  name: 'Skeleton',
+  description:
+    'Displays a decorative or explicitly labelled loading placeholder with a static reduced-motion fallback.',
+  props: [
+    {name: 'label', description: 'Optionally announces what is loading.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except aria-label, children, className, and role',
+  ],
+  example: '<Skeleton label="Loading summary" />',
+  storyId: 'core-skeleton--default',
+} satisfies ComponentDoc;

package/src/Skeleton/Skeleton.tsx

@@ -0,0 +1,45 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const pulse = stylex.keyframes({
+  '50%': {backgroundColor: semanticTokens.colorSurface},
+});
+
+const styles = stylex.create({
+  base: {
+    animationDirection: 'alternate',
+    animationDuration: semanticTokens.durationSlow,
+    animationIterationCount: 'infinite',
+    animationName: {
+      default: pulse,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingStandard,
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusElement,
+    minHeight: semanticTokens.sizeControlMd,
+    width: '100%',
+  },
+});
+
+export interface SkeletonProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'children' | 'className' | 'role'
+> {
+  readonly label?: string;
+}
+
+export function Skeleton({label, ...props}: SkeletonProps) {
+  return (
+    <div
+      {...props}
+      aria-busy={label ? 'true' : undefined}
+      aria-hidden={label ? undefined : 'true'}
+      aria-label={label}
+      role={label ? 'status' : undefined}
+      {...stylex.props(styles.base)}
+    />
+  );
+}

package/src/Skeleton/index.ts

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

package/src/Spinner/Spinner.doc.ts

@@ -0,0 +1,19 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const spinnerDoc = {
+  name: 'Spinner',
+  description:
+    'Announces indeterminate progress with a required accessible label and a static reduced-motion fallback.',
+  props: [
+    {
+      name: 'label',
+      description: 'Names the operation in progress.',
+      required: true,
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except aria-label, children, className, and role',
+  ],
+  example: '<Spinner label="Loading items" />',
+  storyId: 'core-spinner--default',
+} satisfies ComponentDoc;

package/src/Spinner/Spinner.tsx

@@ -0,0 +1,47 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const spin = stylex.keyframes({
+  to: {transform: 'rotate(360deg)'},
+});
+
+const styles = stylex.create({
+  spinner: {
+    animationDuration: semanticTokens.durationSlow,
+    animationIterationCount: 'infinite',
+    animationName: {
+      default: spin,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingStandard,
+    borderBlockStartColor: semanticTokens.colorAccent,
+    borderColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusFull,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    display: 'inline-block',
+    height: semanticTokens.spacingLg,
+    width: semanticTokens.spacingLg,
+  },
+});
+
+export interface SpinnerProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'aria-label' | 'children' | 'className' | 'role'
+> {
+  readonly label: string;
+}
+
+export function Spinner({label, ...props}: SpinnerProps) {
+  return (
+    <span {...props} aria-busy="true" aria-label={label} role="status">
+      <SpinnerVisual />
+    </span>
+  );
+}
+
+export function SpinnerVisual() {
+  return <span aria-hidden="true" {...stylex.props(styles.spinner)} />;
+}

package/src/Spinner/index.ts

@@ -0,0 +1 @@
+export {Spinner, SpinnerVisual, type SpinnerProps} from './Spinner.js';

package/src/Stack/Stack.doc.ts

@@ -0,0 +1,13 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const stackDoc = {
+  name: 'Stack',
+  description: 'Arranges children vertically with semantic spacing.',
+  props: [
+    {name: 'gap', description: 'Optional semantic gap token.'},
+    {name: 'align', description: 'Optional cross-axis alignment.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLDivElement> except className'],
+  example: '<Stack gap="md"><Text>First</Text><Text>Second</Text></Stack>',
+  storyId: 'core-stack--default',
+} satisfies ComponentDoc;

package/src/Stack/Stack.tsx

@@ -0,0 +1,57 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+export type Space = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+const styles = stylex.create({
+  base: {display: 'flex', flexDirection: 'column'},
+  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'},
+});
+
+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,
+} as const;
+
+export interface StackProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly gap?: Space;
+  readonly align?: 'stretch' | 'start' | 'center' | 'end';
+}
+
+export function Stack({
+  gap = 'md',
+  align = 'stretch',
+  children,
+  ...props
+}: StackProps) {
+  return (
+    <div {...props} {...stylex.props(styles.base, gaps[gap], aligns[align])}>
+      {children}
+    </div>
+  );
+}

package/src/Stack/index.ts

@@ -0,0 +1 @@
+export {Stack, type Space, type StackProps} from './Stack.js';

package/src/StatusDot/StatusDot.doc.ts

@@ -0,0 +1,23 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const statusDotDoc = {
+  name: 'StatusDot',
+  description:
+    'Announces a compact live status indicator by its supplied label.',
+  props: [
+    {
+      name: 'aria-label',
+      description: 'Names the represented status.',
+      required: true,
+    },
+    {
+      name: 'tone',
+      description: 'Selects one of the four semantic status tones.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except aria-label, children, className, and role',
+  ],
+  example: '<StatusDot aria-label="Service available" tone="success" />',
+  storyId: 'core-status-dot--default',
+} satisfies ComponentDoc;

package/src/StatusDot/StatusDot.tsx

@@ -0,0 +1,35 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {StatusTone} from '../Badge/index.js';
+
+const styles = stylex.create({
+  base: {
+    borderRadius: semanticTokens.radiusFull,
+    display: 'inline-block',
+    height: semanticTokens.spacingSm,
+    width: semanticTokens.spacingSm,
+  },
+  info: {backgroundColor: semanticTokens.statusInfoText},
+  success: {backgroundColor: semanticTokens.statusSuccessText},
+  warning: {backgroundColor: semanticTokens.statusWarningText},
+  danger: {backgroundColor: semanticTokens.statusDangerText},
+});
+
+/** Props for a labelled live-status indicator using semantic status tones. */
+export interface StatusDotProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'aria-label' | 'children' | 'className' | 'role'
+> {
+  readonly 'aria-label': string;
+  readonly tone?: StatusTone;
+}
+
+export function StatusDot({tone = 'info', ...props}: StatusDotProps) {
+  return (
+    <span {...props} aria-live="polite" role="status">
+      <span aria-hidden="true" {...stylex.props(styles.base, styles[tone])} />
+    </span>
+  );
+}

package/src/StatusDot/index.ts

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

package/src/Table/Table.doc.ts

@@ -0,0 +1,104 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const tableDoc = {
+  name: 'Table',
+  description:
+    'Composes native table, caption, section, row, header, and cell primitives.',
+  props: [
+    {
+      name: 'children',
+      description: 'Supplies semantic table primitives.',
+      required: true,
+    },
+    {
+      name: 'density',
+      description: 'Selects compact, default, or spacious cell rhythm.',
+    },
+    {
+      name: 'dividers',
+      description:
+        'Selects internal row, column, grid, or borderless dividers without adding an outer boundary.',
+    },
+  ],
+  inheritedProps: ['TableHTMLAttributes<HTMLTableElement> except className'],
+  example:
+    '<Table density="compact" dividers="grid"><TableCaption>Values</TableCaption><TableBody /></Table>',
+  storyId: 'core-table--default',
+} satisfies ComponentDoc;
+
+export const tableCaptionDoc = {
+  name: 'TableCaption',
+  description: 'Provides the native accessible name and context for a table.',
+  props: [
+    {
+      name: 'children',
+      description: 'Describes the table contents.',
+      required: true,
+    },
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLTableCaptionElement> except className'],
+  example: '<TableCaption>Quarterly values</TableCaption>',
+  storyId: 'core-table--table-caption',
+} satisfies ComponentDoc;
+
+export const tableHeadDoc = {
+  name: 'TableHead',
+  description: 'Groups a table’s column header rows with native semantics.',
+  props: [
+    {
+      name: 'children',
+      description: 'Supplies header rows.',
+      required: true,
+    },
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLTableSectionElement> except className'],
+  example: '<TableHead><TableRow /></TableHead>',
+  storyId: 'core-table--table-head',
+} satisfies ComponentDoc;
+
+export const tableBodyDoc = {
+  name: 'TableBody',
+  description: 'Groups a table’s data rows with native semantics.',
+  props: [
+    {name: 'children', description: 'Supplies data rows.', required: true},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLTableSectionElement> except className'],
+  example: '<TableBody><TableRow /></TableBody>',
+  storyId: 'core-table--table-body',
+} satisfies ComponentDoc;
+
+export const tableRowDoc = {
+  name: 'TableRow',
+  description: 'Groups related header or data cells in a native table row.',
+  props: [{name: 'children', description: 'Supplies cells.', required: true}],
+  inheritedProps: ['HTMLAttributes<HTMLTableRowElement> except className'],
+  example: '<TableRow><TableCell>Value</TableCell></TableRow>',
+  storyId: 'core-table--table-row',
+} satisfies ComponentDoc;
+
+export const tableHeaderCellDoc = {
+  name: 'TableHeaderCell',
+  description: 'Labels a row or column through native table-header semantics.',
+  props: [
+    {
+      name: 'children',
+      description: 'Supplies the header label.',
+      required: true,
+    },
+    {name: 'scope', description: 'Associates the header with a row or column.'},
+  ],
+  inheritedProps: ['ThHTMLAttributes<HTMLTableCellElement> except className'],
+  example: '<TableHeaderCell scope="col">Name</TableHeaderCell>',
+  storyId: 'core-table--table-header-cell',
+} satisfies ComponentDoc;
+
+export const tableCellDoc = {
+  name: 'TableCell',
+  description: 'Renders one native data cell in a table row.',
+  props: [
+    {name: 'children', description: 'Supplies the cell value.', required: true},
+  ],
+  inheritedProps: ['TdHTMLAttributes<HTMLTableCellElement> except className'],
+  example: '<TableCell>24</TableCell>',
+  storyId: 'core-table--table-cell',
+} satisfies ComponentDoc;