@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/BottomSheetSwitcher/BottomSheetSwitcher.tsx

@@ -0,0 +1,166 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {BottomSheet} from '../BottomSheet/index.js';
+import {Button} from '../Button/index.js';
+import {Icon} from '../Icon/index.js';
+import {useInternationalization} from '../i18n/index.js';
+
+// The back control is a small button, and a small button carries its own
+// inline padding. Negating that padding exactly puts its first letter on the
+// same edge as the sheet's title rather than a step inside it.
+const backBleed = `calc(-1 * ${semanticTokens.spacingSm})`;
+
+const styles = stylex.create({
+  // The heading is the landing point after a switch, so it takes focus; it
+  // stays out of the tab order because it is a heading, not a control.
+  heading: {
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    outlineStyle: 'none',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  views: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: semanticTokens.spacingMd,
+  },
+  back: {
+    display: 'flex',
+    marginInlineStart: backBleed,
+  },
+});
+
+/** One named view a switcher can show inside a single sheet. */
+export interface BottomSheetSwitcherView {
+  readonly content: ReactNode;
+  readonly id: string;
+  readonly parentId?: string;
+  readonly title: ReactNode;
+}
+
+type SharedBottomSheetSwitcherProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role' | 'title'
+> & {
+  readonly backLabel?: string;
+  readonly onDismiss?: () => void;
+  readonly onViewChange?: (viewId: string) => void;
+  readonly open: boolean;
+  readonly views: readonly BottomSheetSwitcherView[];
+};
+
+type ControlledBottomSheetSwitcherProps = SharedBottomSheetSwitcherProps & {
+  readonly defaultViewId?: never;
+  readonly onViewChange: (viewId: string) => void;
+  readonly viewId: string;
+};
+
+type UncontrolledBottomSheetSwitcherProps = SharedBottomSheetSwitcherProps & {
+  readonly defaultViewId?: string;
+  readonly viewId?: never;
+};
+
+/** Props for one sheet whose content swaps between several named views. */
+export type BottomSheetSwitcherProps =
+  ControlledBottomSheetSwitcherProps | UncontrolledBottomSheetSwitcherProps;
+
+/**
+ * Shows one bottom sheet whose content swaps between named views, so a reader
+ * can drill from a summary into a detail without the sheet ever closing. A
+ * view that names a parent gets a back control, and every switch moves focus
+ * to the heading of the view that arrived — otherwise the reader is left on a
+ * button that has just changed meaning underneath them.
+ */
+export function BottomSheetSwitcher({
+  backLabel,
+  defaultViewId,
+  onDismiss,
+  onViewChange,
+  open,
+  viewId,
+  views,
+  ...props
+}: BottomSheetSwitcherProps) {
+  if (views.length === 0) {
+    throw new Error('BottomSheetSwitcher requires at least one view');
+  }
+
+  const {messages} = useInternationalization();
+  const headingRef = useRef<HTMLSpanElement>(null);
+  const shownViewId = useRef<string | undefined>(undefined);
+  const [internalViewId, setInternalViewId] = useState(defaultViewId);
+  const requestedViewId = viewId ?? internalViewId;
+  const current = views.find((view) => view.id === requestedViewId) ?? views[0];
+  const currentId = current.id;
+
+  useEffect(() => {
+    if (!open) {
+      shownViewId.current = undefined;
+      return;
+    }
+    const shown = shownViewId.current;
+    if (shown !== undefined && shown !== currentId) {
+      headingRef.current?.focus();
+    }
+    shownViewId.current = currentId;
+  }, [currentId, open]);
+
+  const parent = views.find((view) => view.id === current.parentId);
+
+  function show(nextViewId: string) {
+    if (viewId === undefined) {
+      setInternalViewId(nextViewId);
+    }
+    onViewChange?.(nextViewId);
+  }
+
+  return (
+    <BottomSheet
+      {...props}
+      onDismiss={onDismiss}
+      open={open}
+      title={
+        <span ref={headingRef} {...stylex.props(styles.heading)} tabIndex={-1}>
+          {current.title}
+        </span>
+      }
+    >
+      <div {...stylex.props(styles.views)}>
+        {parent === undefined ? null : (
+          <div {...stylex.props(styles.back)}>
+            <Button
+              onClick={() => {
+                show(parent.id);
+              }}
+              size="sm"
+              variant="ghost"
+            >
+              <Icon>
+                <path
+                  d="m15 6-6 6 6 6"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                />
+              </Icon>
+              {backLabel ?? messages.back}
+            </Button>
+          </div>
+        )}
+        {current.content}
+      </div>
+    </BottomSheet>
+  );
+}

package/src/BottomSheetSwitcher/index.ts

@@ -0,0 +1,5 @@
+export {
+  BottomSheetSwitcher,
+  type BottomSheetSwitcherProps,
+  type BottomSheetSwitcherView,
+} from './BottomSheetSwitcher.js';

package/src/Box/Box.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const boxDoc = {
+  name: 'Box',
+  description: 'A plain box that spends only token values.',
+  props: [
+    {name: 'bordered', description: 'Draws the default border.'},
+    {name: 'padding', description: 'Selects the inset from the spacing scale.'},
+    {name: 'radius', description: 'Selects the corner treatment.'},
+    {name: 'surface', description: 'Selects the background colour role.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLDivElement> except className'],
+  example: '<Box padding="lg" radius="container" surface="muted">…</Box>',
+  storyId: 'core-box--default',
+} satisfies ComponentDoc;

package/src/Box/Box.tsx

@@ -0,0 +1,98 @@
+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({
+  paddingXs: {padding: semanticTokens.spacingXs},
+  paddingSm: {padding: semanticTokens.spacingSm},
+  paddingMd: {padding: semanticTokens.spacingMd},
+  paddingLg: {padding: semanticTokens.spacingLg},
+  paddingXl: {padding: semanticTokens.spacingXl},
+  padding2xl: {padding: semanticTokens.spacing2xl},
+  canvas: {backgroundColor: semanticTokens.colorCanvas},
+  surface: {backgroundColor: semanticTokens.colorSurface},
+  raised: {backgroundColor: semanticTokens.colorSurfaceRaised},
+  muted: {backgroundColor: semanticTokens.colorSurfaceMuted},
+  radiusInner: {borderRadius: semanticTokens.radiusInner},
+  radiusElement: {borderRadius: semanticTokens.radiusElement},
+  radiusContainer: {borderRadius: semanticTokens.radiusContainer},
+  radiusPage: {borderRadius: semanticTokens.radiusPage},
+  radiusFull: {borderRadius: semanticTokens.radiusFull},
+  bordered: {
+    borderColor: semanticTokens.borderDefault,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+  },
+});
+
+const paddings = {
+  xs: styles.paddingXs,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+  xl: styles.paddingXl,
+  '2xl': styles.padding2xl,
+} as const;
+
+const surfaces = {
+  canvas: styles.canvas,
+  muted: styles.muted,
+  raised: styles.raised,
+  surface: styles.surface,
+} as const;
+
+const radii = {
+  inner: styles.radiusInner,
+  element: styles.radiusElement,
+  container: styles.radiusContainer,
+  page: styles.radiusPage,
+  full: styles.radiusFull,
+} as const;
+
+/** Background roles a box can take from the token contract. */
+export type BoxSurface = keyof typeof surfaces;
+
+/** Corner treatments a box can take from the token contract. */
+export type BoxRadius = keyof typeof radii;
+
+/** Props for the plain token-aware box. */
+export interface BoxProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly bordered?: boolean;
+  readonly padding?: Space;
+  readonly radius?: BoxRadius;
+  readonly surface?: BoxSurface;
+}
+
+/**
+ * A box with no meaning of its own, spending only token values. Reach for it
+ * when a layout needs a surface or some padding and none of the named
+ * containers — `Card`, `Section` — would be telling the truth about what the
+ * thing is.
+ */
+export function Box({
+  bordered = false,
+  children,
+  padding,
+  radius,
+  surface,
+  ...props
+}: BoxProps) {
+  return (
+    <div
+      {...props}
+      {...stylex.props(
+        padding === undefined ? undefined : paddings[padding],
+        surface === undefined ? undefined : surfaces[surface],
+        radius === undefined ? undefined : radii[radius],
+        bordered && styles.bordered,
+      )}
+    >
+      {children}
+    </div>
+  );
+}

package/src/Box/index.ts

@@ -0,0 +1 @@
+export {Box, type BoxProps, type BoxRadius, type BoxSurface} from './Box.js';

package/src/Breadcrumbs/Breadcrumbs.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const breadcrumbsDoc = {
+  name: 'Breadcrumbs',
+  description: 'Shows the path leading to the current page.',
+  props: [
+    {
+      name: 'items',
+      description: 'Supplies the trail from root to current page.',
+    },
+    {name: 'label', description: 'Names the navigation landmark.'},
+    {name: 'separator', description: 'Replaces the decorative divider glyph.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLElement> except children and className'],
+  example:
+    '<Breadcrumbs items={[{href: "/", label: "Home"}, {label: "Release"}]} />',
+  storyId: 'core-breadcrumbs--default',
+} satisfies ComponentDoc;

package/src/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,124 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Link} from '../navigation/index.js';
+
+const styles = stylex.create({
+  nav: {fontFamily: semanticTokens.fontFamilyBody},
+  list: {
+    alignItems: 'center',
+    columnGap: semanticTokens.spacingXs,
+    display: 'flex',
+    flexWrap: 'wrap',
+    listStyleType: 'none',
+    marginBlock: 0,
+    marginInline: 0,
+    paddingInlineStart: 0,
+    rowGap: semanticTokens.spacingXs,
+  },
+  item: {
+    alignItems: 'center',
+    columnGap: semanticTokens.spacingXs,
+    display: 'flex',
+  },
+  // A trail is text and separators. There is no chip, no fill and no radius
+  // here: the path is read, not clicked as a set of objects. The separator is
+  // set as an eyebrow — smallest size, third rank of ink — because a mark cut
+  // at the same size as the steps it parts reads as another step.
+  separator: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+  },
+  current: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+  },
+  // The trail reads as one line, so the links match the current-page text
+  // rather than inheriting the surrounding body size.
+  link: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    textDecorationLine: 'none',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {
+      color: semanticTokens.colorText,
+      textDecorationLine: 'underline',
+    },
+  },
+});
+
+/** One step on the path to the current page. */
+export interface BreadcrumbItem {
+  readonly href?: string;
+  readonly label: ReactNode;
+}
+
+/** Props for the trail leading to the current page. */
+export interface BreadcrumbsProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'children' | 'className'
+> {
+  readonly items: readonly BreadcrumbItem[];
+  readonly label?: string;
+  readonly separator?: ReactNode;
+}
+
+/**
+ * Shows the path to the current page. The last item is rendered as text and
+ * marked `aria-current`, because a link to the page you are on is not a link.
+ */
+export function Breadcrumbs({
+  items,
+  label = 'Breadcrumb',
+  separator = '/',
+  ...props
+}: BreadcrumbsProps) {
+  return (
+    <nav {...props} aria-label={label} {...stylex.props(styles.nav)}>
+      <ol {...stylex.props(styles.list)}>
+        {items.map(({href, label: itemLabel}, index) => {
+          const last = index === items.length - 1;
+
+          return (
+            <li key={index} {...stylex.props(styles.item)}>
+              {href === undefined || last ? (
+                <span
+                  {...(last ? {'aria-current': 'page' as const} : {})}
+                  {...stylex.props(styles.current)}
+                >
+                  {itemLabel}
+                </span>
+              ) : (
+                <Link href={href} {...stylex.props(styles.link)}>
+                  {itemLabel}
+                </Link>
+              )}
+              {last ? null : (
+                <span aria-hidden="true" {...stylex.props(styles.separator)}>
+                  {separator}
+                </span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/src/Breadcrumbs/index.ts

@@ -0,0 +1,5 @@
+export {
+  Breadcrumbs,
+  type BreadcrumbItem,
+  type BreadcrumbsProps,
+} from './Breadcrumbs.js';

package/src/Button/Button.tsx

@@ -11,6 +11,7 @@ const styles = stylex.create({
     borderRadius: semanticTokens.radiusElement,
     borderStyle: semanticTokens.borderStyle,
     borderWidth: semanticTokens.borderWidth,
+    cursor: 'pointer',
     display: 'inline-flex',
     fontFamily: semanticTokens.fontFamilyBody,
     fontWeight: semanticTokens.fontWeightMedium,
@@ -18,10 +19,14 @@ const styles = stylex.create({
     justifyContent: 'center',
     lineHeight: semanticTokens.lineHeightBody,
     position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
     ':disabled': {
       backgroundColor: semanticTokens.colorDisabledSurface,
       borderColor: semanticTokens.borderDisabled,
       color: semanticTokens.colorDisabledText,
+      cursor: 'default',
     },
     ':focus-visible': {
       outlineColor: semanticTokens.colorFocus,
@@ -30,32 +35,47 @@ const styles = stylex.create({
       outlineWidth: semanticTokens.focusWidth,
     },
   },
+  // A button wears a label, and a label is set at the label size: the console
+  // sets its buttons a step below the body copy they sit among, so the row
+  // reads as a sentence with an action at the end rather than two competing
+  // voices. Only the largest size comes up to body size.
   sm: {
     fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
     height: semanticTokens.sizeControlSm,
     paddingInline: semanticTokens.spacingSm,
   },
   md: {
-    fontSize: semanticTokens.fontSizeMd,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
     height: semanticTokens.sizeControlMd,
     paddingInline: semanticTokens.spacingMd,
   },
   lg: {
     fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
     height: semanticTokens.sizeControlLg,
     paddingInline: semanticTokens.spacingLg,
   },
+  // The signature: ink ground, paper letters. The emphatic button is a seal
+  // pressed on the sheet, not a brand-coloured rectangle — the accent's jobs
+  // are the focus ring, the selection mark and a link on hover, all of them
+  // thin, and filling a control with it is the one way to make this system
+  // look like somebody else's. Ink is already the darkest thing on the page,
+  // so the pointer states run down the ranks of ink rather than deeper; the
+  // overlay wash the coloured variants use is invisible over a fill this dark
+  // in light mode and this pale in dark mode.
   primary: {
-    backgroundColor: semanticTokens.colorAccent,
-    borderColor: semanticTokens.colorAccent,
+    backgroundColor: semanticTokens.colorText,
+    borderColor: semanticTokens.colorText,
     color: semanticTokens.colorTextOnAccent,
     ':hover:not(:disabled):not(:active)': {
-      backgroundColor: semanticTokens.colorAccentHover,
-      borderColor: semanticTokens.colorAccentHover,
+      backgroundColor: semanticTokens.colorTextSecondary,
+      borderColor: semanticTokens.colorTextSecondary,
     },
     ':active:not(:disabled)': {
-      backgroundColor: semanticTokens.colorAccentActive,
-      borderColor: semanticTokens.colorAccentActive,
+      backgroundColor: semanticTokens.colorTextMuted,
+      borderColor: semanticTokens.colorTextMuted,
     },
   },
   secondary: {
@@ -71,15 +91,20 @@ const styles = stylex.create({
       borderColor: semanticTokens.borderInteractive,
     },
   },
+  // A ghost is the subordinate action in whatever row it appears in, so it
+  // takes the available rank of ink and comes up to full ink under the pointer.
+  // Reaching for `colorText` at rest made it argue with the button beside it.
   ghost: {
     backgroundColor: 'transparent',
     borderColor: 'transparent',
-    color: semanticTokens.colorText,
+    color: semanticTokens.colorTextSecondary,
     ':hover:not(:disabled):not(:active)': {
       backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
     },
     ':active:not(:disabled)': {
       backgroundColor: semanticTokens.colorOverlayActive,
+      color: semanticTokens.colorText,
     },
   },
   destructive: {
@@ -93,7 +118,9 @@ const styles = stylex.create({
       backgroundImage: `linear-gradient(${semanticTokens.colorOverlayActive}, ${semanticTokens.colorOverlayActive})`,
     },
   },
-  loading: {cursor: 'progress'},
+  // A loading button is disabled, so the waiting cursor has to be declared
+  // against the same state the disabled cursor is, or it never wins.
+  loading: {cursor: 'progress', ':disabled': {cursor: 'progress'}},
   iconOnly: {paddingInline: 0},
   iconSm: {width: semanticTokens.sizeControlSm},
   iconMd: {width: semanticTokens.sizeControlMd},

package/src/ButtonGroup/ButtonGroup.doc.ts

@@ -0,0 +1,19 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const buttonGroupDoc = {
+  name: 'ButtonGroup',
+  description: 'Groups related actions so they read as one control.',
+  props: [
+    {name: 'children', description: 'Supplies the grouped actions.'},
+    {name: 'label', description: 'Names the group for assistive technology.'},
+    {
+      name: 'orientation',
+      description: 'Selects the axis arrow keys travel along.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except aria-label, children, className, and role',
+  ],
+  example: '<ButtonGroup label="Alignment"><Button>Left</Button></ButtonGroup>',
+  storyId: 'core-button-group--default',
+} satisfies ComponentDoc;

package/src/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,52 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useListFocus, type ListOrientation} from '../hooks/useListFocus.js';
+
+const styles = stylex.create({
+  group: {
+    alignItems: 'center',
+    display: 'inline-flex',
+    gap: semanticTokens.spacingXs,
+  },
+  horizontal: {flexDirection: 'row'},
+  vertical: {alignItems: 'stretch', flexDirection: 'column'},
+});
+
+/** Props for a set of related actions treated as one control. */
+export interface ButtonGroupProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'aria-label' | 'children' | 'className' | 'role'
+> {
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly orientation?: ListOrientation;
+}
+
+/**
+ * Groups related actions so they read as one control. Unlike `Toolbar` the
+ * actions here are alternatives to each other rather than separate commands.
+ */
+export function ButtonGroup({
+  children,
+  label,
+  orientation = 'horizontal',
+  ...props
+}: ButtonGroupProps) {
+  const groupRef = useRef<HTMLDivElement>(null);
+  const {onKeyDown} = useListFocus(groupRef, {orientation});
+
+  return (
+    <div
+      {...props}
+      aria-label={label}
+      onKeyDown={onKeyDown}
+      ref={groupRef}
+      role="group"
+      {...stylex.props(styles.group, styles[orientation])}
+    >
+      {children}
+    </div>
+  );
+}

package/src/ButtonGroup/index.ts

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

package/src/Calendar/Calendar.doc.ts

@@ -0,0 +1,28 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const calendarDoc = {
+  name: 'Calendar',
+  description: 'Selects a date from a month grid.',
+  props: [
+    {
+      name: 'defaultValue',
+      description: 'Sets the initial uncontrolled ISO date.',
+    },
+    {name: 'formatDay', description: 'Builds the accessible name of one day.'},
+    {
+      name: 'formatMonth',
+      description: 'Builds the heading for the shown month.',
+    },
+    {name: 'label', description: 'Names the grid for assistive technology.'},
+    {name: 'max', description: 'Blocks dates after this ISO date.'},
+    {name: 'min', description: 'Blocks dates before this ISO date.'},
+    {name: 'onValueChange', description: 'Receives the chosen ISO date.'},
+    {name: 'value', description: 'Controls the selected ISO date.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, defaultValue, onChange, and role',
+  ],
+  example:
+    '<Calendar label="Release date" onValueChange={setDate} value={date} />',
+  storyId: 'core-calendar--default',
+} satisfies ComponentDoc;