@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Avatar/Avatar.tsx

@@ -0,0 +1,100 @@
+import * as stylex from '@stylexjs/stylex';
+import {useState, type HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  avatar: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusFull,
+    color: semanticTokens.colorTextSecondary,
+    display: 'inline-flex',
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontWeight: semanticTokens.fontWeightMedium,
+    justifyContent: 'center',
+    lineHeight: 1,
+    overflow: 'hidden',
+    userSelect: 'none',
+  },
+  sm: {
+    fontSize: semanticTokens.fontSizeXs,
+    height: semanticTokens.sizeControlSm,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    width: semanticTokens.sizeControlSm,
+  },
+  md: {
+    fontSize: semanticTokens.fontSizeSm,
+    height: semanticTokens.sizeControlMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    width: semanticTokens.sizeControlMd,
+  },
+  lg: {
+    fontSize: semanticTokens.fontSizeMd,
+    height: semanticTokens.sizeControlLg,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    width: semanticTokens.sizeControlLg,
+  },
+  image: {
+    display: 'block',
+    height: '100%',
+    objectFit: 'cover',
+    width: '100%',
+  },
+});
+
+/** Sizes an avatar can occupy, aligned to the control scale. */
+export type AvatarSize = 'sm' | 'md' | 'lg';
+
+/** Props for a person or entity's likeness. */
+export interface AvatarProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'children' | 'className'
+> {
+  readonly name: string;
+  readonly size?: AvatarSize;
+  readonly src?: string;
+}
+
+// Initials fall back to the first letters of the first and last word.
+function initials(name: string) {
+  const words = name.trim().split(/\s+/u).filter(Boolean);
+  if (words.length === 0) {
+    return '';
+  }
+  const first = words[0]?.[0] ?? '';
+  const last = words.length > 1 ? (words[words.length - 1]?.[0] ?? '') : '';
+  return (first + last).toUpperCase();
+}
+
+/**
+ * Shows one person or entity. The name is the accessible label whether an
+ * image loads or not, so a broken image never leaves an unnamed circle.
+ */
+export function Avatar({name, size = 'md', src, ...props}: AvatarProps) {
+  const [failed, setFailed] = useState(false);
+  const showImage = src !== undefined && !failed;
+
+  return (
+    <span
+      {...props}
+      aria-label={name}
+      role="img"
+      {...stylex.props(styles.avatar, styles[size])}
+    >
+      {showImage ? (
+        <img
+          alt=""
+          onError={() => {
+            setFailed(true);
+          }}
+          src={src}
+          {...stylex.props(styles.image)}
+        />
+      ) : (
+        <span aria-hidden="true">{initials(name)}</span>
+      )}
+    </span>
+  );
+}

package/src/Avatar/index.ts

@@ -0,0 +1 @@
+export {Avatar, type AvatarProps, type AvatarSize} from './Avatar.js';

package/src/AvatarGroup/AvatarGroup.doc.ts

@@ -0,0 +1,17 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const avatarGroupDoc = {
+  name: 'AvatarGroup',
+  description: 'Shows several people as one capped, overlapping row.',
+  props: [
+    {name: 'label', description: 'Names what the group of people represents.'},
+    {name: 'max', description: 'Caps how many avatars are drawn.'},
+    {name: 'members', description: 'Supplies the people in reading order.'},
+    {name: 'size', description: 'Selects the size of every avatar.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example: '<AvatarGroup label="Reviewers" members={reviewers} />',
+  storyId: 'core-avatar-group--default',
+} satisfies ComponentDoc;

package/src/AvatarGroup/AvatarGroup.tsx

@@ -0,0 +1,124 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Avatar, type AvatarSize} from '../Avatar/index.js';
+
+const styles = stylex.create({
+  group: {
+    alignItems: 'center',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+  },
+  // The ring is painted in the surface the stack sits on, so the overlap
+  // reads as one avatar in front of another rather than as a merged blob.
+  slot: {
+    borderColor: semanticTokens.colorSurface,
+    borderRadius: semanticTokens.radiusFull,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.focusWidth,
+    display: 'inline-flex',
+    marginInlineStart: `calc(-1 * ${semanticTokens.spacingSm})`,
+  },
+  first: {marginInlineStart: 0},
+  overflow: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusFull,
+    color: semanticTokens.colorTextSecondary,
+    display: 'inline-flex',
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: semanticTokens.fontWeightMedium,
+    justifyContent: 'center',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: 1,
+  },
+  overflowSm: {
+    fontSize: semanticTokens.fontSizeXs,
+    height: semanticTokens.sizeControlSm,
+    width: semanticTokens.sizeControlSm,
+  },
+  overflowMd: {
+    fontSize: semanticTokens.fontSizeSm,
+    height: semanticTokens.sizeControlMd,
+    width: semanticTokens.sizeControlMd,
+  },
+  overflowLg: {
+    fontSize: semanticTokens.fontSizeMd,
+    height: semanticTokens.sizeControlLg,
+    width: semanticTokens.sizeControlLg,
+  },
+});
+
+const overflowSizes = {
+  sm: styles.overflowSm,
+  md: styles.overflowMd,
+  lg: styles.overflowLg,
+} as const;
+
+/** One member of an avatar group. */
+export interface AvatarGroupMember {
+  readonly name: string;
+  readonly src?: string;
+}
+
+/** Props for a capped, overlapping row of avatars. */
+export interface AvatarGroupProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly label: string;
+  readonly max?: number;
+  readonly members: readonly AvatarGroupMember[];
+  readonly size?: AvatarSize;
+}
+
+/**
+ * Shows several people as one overlapping row. Everyone past `max` is counted
+ * rather than drawn, and the group carries a single label so a screen reader
+ * hears "4 reviewers" instead of four separate images.
+ */
+export function AvatarGroup({
+  label,
+  max = 4,
+  members,
+  size = 'md',
+  ...props
+}: AvatarGroupProps) {
+  const shown = members.slice(0, max);
+  const hidden = members.length - shown.length;
+
+  return (
+    <div
+      {...props}
+      aria-label={`${label}: ${members.length}`}
+      role="group"
+      {...stylex.props(styles.group)}
+    >
+      {shown.map((member, index) => (
+        <span
+          key={member.name}
+          {...stylex.props(styles.slot, index === 0 && styles.first)}
+        >
+          <Avatar
+            name={member.name}
+            size={size}
+            {...(member.src === undefined ? {} : {src: member.src})}
+          />
+        </span>
+      ))}
+      {hidden > 0 ? (
+        <span {...stylex.props(styles.slot)}>
+          <span
+            aria-hidden="true"
+            {...stylex.props(styles.overflow, overflowSizes[size])}
+          >
+            +{hidden}
+          </span>
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/src/AvatarGroup/index.ts

@@ -0,0 +1,5 @@
+export {
+  AvatarGroup,
+  type AvatarGroupMember,
+  type AvatarGroupProps,
+} from './AvatarGroup.js';

package/src/Badge/Badge.tsx

@@ -15,6 +15,7 @@ const styles = stylex.create({
     display: 'inline-flex',
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
     fontWeight: semanticTokens.fontWeightMedium,
     paddingBlock: semanticTokens.spacingXs,
     paddingInline: semanticTokens.spacingSm,

package/src/Banner/Banner.doc.ts

@@ -0,0 +1,17 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const bannerDoc = {
+  name: 'Banner',
+  description: 'Announces something about the whole page or account.',
+  props: [
+    {name: 'actions', description: 'Places a follow-up action at the end.'},
+    {name: 'children', description: 'Supplies the announcement.'},
+    {name: 'tone', description: 'Selects the semantic status colour.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and role',
+  ],
+  example:
+    '<Banner tone="warning">Billing details expire in three days.</Banner>',
+  storyId: 'core-banner--default',
+} satisfies ComponentDoc;

package/src/Banner/Banner.tsx

@@ -0,0 +1,87 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {StatusTone} from '../Badge/index.js';
+
+const styles = stylex.create({
+  // A band of dyed paper, set in the darker shade of the same dye. It carries
+  // no outline: an edge in the tone colour draws the announcement twice, and
+  // the tint is already the whole of the signal at page width.
+  banner: {
+    alignItems: 'center',
+    // Every corner in the system is three pixels. A square-cornered box is
+    // the one shape here that belongs to no theme.
+    borderRadius: semanticTokens.radiusContainer,
+    borderStyle: 'none',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    gap: semanticTokens.spacingMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  info: {
+    backgroundColor: semanticTokens.statusInfoSurface,
+    color: semanticTokens.statusInfoText,
+  },
+  success: {
+    backgroundColor: semanticTokens.statusSuccessSurface,
+    color: semanticTokens.statusSuccessText,
+  },
+  warning: {
+    backgroundColor: semanticTokens.statusWarningSurface,
+    color: semanticTokens.statusWarningText,
+  },
+  danger: {
+    backgroundColor: semanticTokens.statusDangerSurface,
+    color: semanticTokens.statusDangerText,
+  },
+  message: {flexGrow: 1, minWidth: 0},
+  actions: {
+    alignItems: 'center',
+    display: 'flex',
+    flexShrink: 0,
+    gap: semanticTokens.spacingSm,
+  },
+});
+
+/** Props for a page-width announcement. */
+export interface BannerProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role'
+> {
+  readonly actions?: ReactNode;
+  readonly children: ReactNode;
+  readonly tone?: StatusTone;
+}
+
+/**
+ * Announces something about the whole page or account, spanning its full
+ * width. Use `Alert` for a message about one region and `Toast` for one that
+ * passes on its own.
+ */
+export function Banner({
+  actions,
+  children,
+  tone = 'info',
+  ...props
+}: BannerProps) {
+  const isDanger = tone === 'danger';
+
+  return (
+    <div
+      {...props}
+      aria-live={isDanger ? 'assertive' : 'polite'}
+      role={isDanger ? 'alert' : 'status'}
+      {...stylex.props(styles.banner, styles[tone])}
+    >
+      <div {...stylex.props(styles.message)}>{children}</div>
+      {actions === undefined ? null : (
+        <div {...stylex.props(styles.actions)}>{actions}</div>
+      )}
+    </div>
+  );
+}

package/src/Banner/index.ts

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

package/src/Blockquote/Blockquote.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const blockquoteDoc = {
+  name: 'Blockquote',
+  description: 'Sets off quoted text and names its source.',
+  props: [
+    {name: 'attribution', description: 'Names where the quotation came from.'},
+    {name: 'children', description: 'Supplies the quoted text.'},
+  ],
+  inheritedProps: [
+    'BlockquoteHTMLAttributes<HTMLQuoteElement> except children and className',
+  ],
+  example: '<Blockquote attribution="Ada Lovelace">…</Blockquote>',
+  storyId: 'core-blockquote--default',
+} satisfies ComponentDoc;

package/src/Blockquote/Blockquote.tsx

@@ -0,0 +1,55 @@
+import * as stylex from '@stylexjs/stylex';
+import type {BlockquoteHTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  // A quote is marked by a rule in the strong border, never by a tinted
+  // block: the words stay on the same paper as the copy around them.
+  quote: {
+    borderInlineStartColor: semanticTokens.borderStrong,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.focusWidth,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    gap: semanticTokens.spacingSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+    paddingInlineStart: semanticTokens.spacingMd,
+  },
+  attribution: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+});
+
+/** Props for quoted text and its source. */
+export interface BlockquoteProps extends Omit<
+  BlockquoteHTMLAttributes<HTMLQuoteElement>,
+  'children' | 'className'
+> {
+  readonly attribution?: ReactNode;
+  readonly children: ReactNode;
+}
+
+/**
+ * Sets off quoted text. The attribution is emitted inside the quote as a
+ * `footer`, which is where the HTML spec puts the source of a quotation.
+ */
+export function Blockquote({attribution, children, ...props}: BlockquoteProps) {
+  return (
+    <blockquote {...props} {...stylex.props(styles.quote)}>
+      {children}
+      {attribution === undefined ? null : (
+        <footer {...stylex.props(styles.attribution)}>{attribution}</footer>
+      )}
+    </blockquote>
+  );
+}

package/src/Blockquote/index.ts

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

package/src/BottomSheet/BottomSheet.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const bottomSheetDoc = {
+  name: 'BottomSheet',
+  description: 'Presents a modal panel anchored to the bottom edge.',
+  props: [
+    {name: 'children', description: 'Supplies the panel body.'},
+    {name: 'onDismiss', description: 'Runs on Escape or a scrim click.'},
+    {name: 'open', description: 'Controls whether the panel renders.'},
+    {name: 'title', description: 'Names the panel for assistive technology.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, role, and title',
+  ],
+  example:
+    '<BottomSheet onDismiss={close} open={open} title="Filters">...</BottomSheet>',
+  storyId: 'core-bottom-sheet--default',
+} satisfies ComponentDoc;

package/src/BottomSheet/BottomSheet.tsx

@@ -0,0 +1,119 @@
+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';
+
+const sheetEnter = stylex.keyframes({
+  from: {transform: 'translateY(100%)'},
+  to: {transform: 'translateY(0)'},
+});
+
+const styles = stylex.create({
+  surface: {
+    animationDuration: semanticTokens.durationModerate,
+    animationName: {
+      default: sheetEnter,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingEmphasized,
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderStartEndRadius: semanticTokens.radiusContainer,
+    borderStartStartRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationHigh,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    insetBlockEnd: 0,
+    // The sheet is lifted off the side edges rather than welded to them: it is
+    // one more sheet of paper laid over the page, not a second page.
+    insetInline: semanticTokens.spacingXl,
+    maxHeight: '85vh',
+    // Each band owns its own padding so a row can still bleed to the edge.
+    overflow: 'hidden',
+    // The panel pins itself to the viewport edge rather than settling into the
+    // scrim's centred flex box, which is where every other modal surface sits.
+    position: 'fixed',
+  },
+  handle: {
+    display: 'flex',
+    justifyContent: 'center',
+    paddingBlockEnd: semanticTokens.spacingXs,
+    paddingBlockStart: semanticTokens.spacingSm,
+  },
+  // Three pixels, like every other corner. A capsule here would be the one
+  // rounded shape in the system that is neither a dot nor a knob.
+  grip: {
+    backgroundColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusInner,
+    height: semanticTokens.spacingXs,
+    width: semanticTokens.spacing2xl,
+  },
+  title: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeLg,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingHeading,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+    paddingBlockEnd: semanticTokens.spacingSm,
+    paddingBlockStart: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  content: {
+    minHeight: 0,
+    overflowY: 'auto',
+    paddingBlockEnd: semanticTokens.spacingLg,
+    paddingInline: semanticTokens.spacingLg,
+  },
+});
+
+/** Props for a modal panel that enters from the bottom edge. */
+export interface BottomSheetProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'role' | 'title'
+> {
+  readonly children?: ReactNode;
+  readonly onDismiss?: () => void;
+  readonly open: boolean;
+  readonly title: ReactNode;
+}
+
+/**
+ * Presents a modal panel anchored to the bottom edge, where a thumb can reach
+ * it. It carries the same focus trap and scroll lock as Dialog.
+ */
+export function BottomSheet({
+  children,
+  onDismiss,
+  open,
+  title,
+  ...props
+}: BottomSheetProps) {
+  const titleId = useId();
+
+  return (
+    <Overlay {...(onDismiss ? {onDismiss} : {})} open={open}>
+      <div
+        {...props}
+        aria-labelledby={titleId}
+        aria-modal="true"
+        role="dialog"
+        {...stylex.props(styles.surface)}
+      >
+        <div aria-hidden="true" {...stylex.props(styles.handle)}>
+          <span {...stylex.props(styles.grip)} />
+        </div>
+        <h2 id={titleId} {...stylex.props(styles.title)}>
+          {title}
+        </h2>
+        <div {...stylex.props(styles.content, scrolling.region)}>
+          {children}
+        </div>
+      </div>
+    </Overlay>
+  );
+}

package/src/BottomSheet/index.ts

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

package/src/BottomSheetSwitcher/BottomSheetSwitcher.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const bottomSheetSwitcherDoc = {
+  name: 'BottomSheetSwitcher',
+  description: 'Swaps one sheet between several named views.',
+  props: [
+    {name: 'backLabel', description: 'Names the control back to the parent.'},
+    {name: 'defaultViewId', description: 'Sets the initial uncontrolled view.'},
+    {name: 'onDismiss', description: 'Runs on Escape or a scrim click.'},
+    {name: 'onViewChange', description: 'Receives the next view id.'},
+    {name: 'open', description: 'Controls whether the sheet renders.'},
+    {name: 'viewId', description: 'Controls which view is shown.'},
+    {name: 'views', description: 'Supplies each view and its parent.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, role, and title',
+  ],
+  example:
+    '<BottomSheetSwitcher onDismiss={close} open={open} views={views} />',
+  storyId: 'core-bottom-sheet-switcher--default',
+} satisfies ComponentDoc;