@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/DropdownMenu/DropdownMenu.tsx

@@ -0,0 +1,197 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useEffect,
+  useRef,
+  type ButtonHTMLAttributes,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {focusableElements} from '../hooks/focusableSelector.js';
+import {useListFocus} from '../hooks/useListFocus.js';
+import type {Alignment, Placement} from '../hooks/useAnchoredPosition.js';
+import {Item} from '../Item/index.js';
+import {Popover} from '../Popover/index.js';
+
+// A menu stays wide enough for a two-word action plus its shortcut; the scale
+// stops at 38px, so the floor is a named multiple of it rather than a literal.
+// The bleed is added back because the list negates the popover's padding.
+const menuBleed = `calc(-1 * ${semanticTokens.spacingMd})`;
+const menuMinWidth = `calc(${semanticTokens.spacing2xl} * 5 + ${semanticTokens.spacingMd} * 2)`;
+
+// The same bookmark the sidebar draws beside the reader's page: two hairlines
+// wide, short of the row's full height so it reads as a stroke laid on the
+// row rather than as a rule dividing it.
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const markHeight = '64%';
+
+const styles = stylex.create({
+  // The list negates the popover's padding exactly and puts it back on each
+  // row, so a hover wash runs the full width of the plate instead of floating
+  // as a rectangle inside it. Rows sit flush: a gap between actions reads as
+  // separate controls rather than as one menu.
+  menu: {
+    display: 'flex',
+    flexDirection: 'column',
+    marginBlock: menuBleed,
+    marginInline: menuBleed,
+    minWidth: menuMinWidth,
+    paddingBlock: semanticTokens.spacingXs,
+  },
+  // A row inside a plate is a solid block, not a small outlined box: no
+  // hairline, no radius of its own, the state carried entirely by the fill.
+  // At rest it holds the second rank of ink, because every row in a menu is
+  // merely available; the one under the pointer rises to the first and takes
+  // the bookmark, so the pointer is marked twice over and filled never.
+  item: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingMd,
+    position: 'relative',
+    textAlign: 'start',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    '::before': {
+      backgroundColor: semanticTokens.colorAccent,
+      content: '',
+      height: {default: 0, ':hover:not(:disabled)': markHeight},
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      transitionDuration: semanticTokens.durationModerate,
+      transitionProperty: 'height',
+      transitionTimingFunction: semanticTokens.easingStandard,
+      width: markWidth,
+    },
+    ':disabled': {
+      color: semanticTokens.colorDisabledText,
+      cursor: 'default',
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+});
+
+/** Props for a menu of actions anchored to a trigger. */
+export interface DropdownMenuProps {
+  readonly alignment?: Alignment;
+  readonly anchorRef: RefObject<HTMLElement | null>;
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly onDismiss?: () => void;
+  readonly open: boolean;
+  readonly placement?: Placement;
+}
+
+/**
+ * Presents a list of actions beside its trigger. The menu is one tab stop:
+ * arrow keys, Home, and End move between items, and Escape closes it.
+ */
+export function DropdownMenu({
+  alignment = 'start',
+  anchorRef,
+  children,
+  label,
+  onDismiss,
+  open,
+  placement = 'bottom',
+}: DropdownMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null);
+  const {onKeyDown} = useListFocus(menuRef, {orientation: 'vertical'});
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    // Waiting a frame lets the portalled surface mount before focus moves.
+    const frame = requestAnimationFrame(() => {
+      const menu = menuRef.current;
+      if (menu) {
+        focusableElements(menu)[0]?.focus({preventScroll: true});
+      }
+    });
+
+    return () => {
+      cancelAnimationFrame(frame);
+    };
+  }, [open]);
+
+  return (
+    <Popover
+      alignment={alignment}
+      anchorRef={anchorRef}
+      {...(onDismiss ? {onDismiss} : {})}
+      open={open}
+      placement={placement}
+      role="presentation"
+    >
+      <div
+        aria-label={label}
+        onKeyDown={onKeyDown}
+        ref={menuRef}
+        role="menu"
+        {...stylex.props(styles.menu)}
+      >
+        {children}
+      </div>
+    </Popover>
+  );
+}
+
+/** Props for one action inside a `DropdownMenu`. */
+export interface DropdownMenuItemProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'className' | 'role'
+> {
+  readonly description?: ReactNode;
+  readonly leading?: ReactNode;
+  readonly trailing?: ReactNode;
+}
+
+/** Renders one menu action with the shared leading/label/trailing rhythm. */
+export function DropdownMenuItem({
+  children,
+  description,
+  leading,
+  trailing,
+  type = 'button',
+  ...props
+}: DropdownMenuItemProps) {
+  return (
+    <button
+      {...props}
+      role="menuitem"
+      type={type}
+      {...stylex.props(styles.item)}
+    >
+      <Item
+        {...(description === undefined ? {} : {description})}
+        {...(leading === undefined ? {} : {leading})}
+        {...(trailing === undefined ? {} : {trailing})}
+      >
+        {children}
+      </Item>
+    </button>
+  );
+}

package/src/DropdownMenu/index.ts

@@ -0,0 +1,6 @@
+export {
+  DropdownMenu,
+  DropdownMenuItem,
+  type DropdownMenuItemProps,
+  type DropdownMenuProps,
+} from './DropdownMenu.js';

package/src/EmptyState/EmptyState.tsx

@@ -6,29 +6,52 @@ import {semanticTokens} from '../authoring.stylex.js';
 const copyWidth = `calc(${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl})`;
 
 const styles = stylex.create({
+  // A page with nothing written on it is still a page. Without an edge the
+  // block reads as content that failed to arrive rather than as a place
+  // waiting for it, so the empty state sits on a plate like any other set.
   root: {
     alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurface,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationMedium,
     color: semanticTokens.colorText,
     display: 'flex',
     flexDirection: 'column',
     fontFamily: semanticTokens.fontFamilyBody,
-    gap: semanticTokens.spacingMd,
-    padding: semanticTokens.spacing2xl,
+    gap: semanticTokens.spacingSm,
+    // The foot is tighter than the head: the actions close the block, and an
+    // even inset leaves them stranded in the middle of the lower half.
+    paddingBlockEnd: semanticTokens.spacingXl,
+    paddingBlockStart: semanticTokens.spacing2xl,
+    paddingInline: semanticTokens.spacing2xl,
     textAlign: 'center',
   },
+  // Written as the same three longhands the default size uses: a shorthand
+  // here would lose to them whichever order the two objects arrive in.
   compact: {
     gap: semanticTokens.spacingSm,
-    padding: semanticTokens.spacingLg,
+    paddingBlockEnd: semanticTokens.spacingLg,
+    paddingBlockStart: semanticTokens.spacingLg,
+    paddingInline: semanticTokens.spacingLg,
   },
+  // Three ranks, not one. The sentence naming the absence is what is current
+  // and takes the display face; the sentence explaining what to do about it is
+  // context, and setting both in full ink made the block read as a warning.
   title: {
-    fontFamily: semanticTokens.fontFamilyHeading,
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyDisplay,
     fontSize: semanticTokens.fontSizeLg,
-    fontWeight: semanticTokens.fontWeightStrong,
+    letterSpacing: semanticTokens.letterSpacingHeading,
+    lineHeight: semanticTokens.lineHeightHeading,
+    fontWeight: semanticTokens.fontWeightMedium,
     margin: 0,
     maxInlineSize: copyWidth,
   },
   detail: {
-    fontSize: semanticTokens.fontSizeMd,
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
     lineHeight: semanticTokens.lineHeightBody,
     margin: 0,
     maxInlineSize: copyWidth,

package/src/Eyebrow/Eyebrow.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const eyebrowDoc = {
+  name: 'Eyebrow',
+  description: 'Names a thing without competing with it.',
+  props: [
+    {name: 'children', description: 'Supplies the label.'},
+    {
+      name: 'tone',
+      description: 'Optional ink rank: "secondary", "muted", or "danger".',
+    },
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLSpanElement> except className'],
+  example: '<Eyebrow>Recent activity</Eyebrow>',
+  storyId: 'core-eyebrow--default',
+} satisfies ComponentDoc;

package/src/Eyebrow/Eyebrow.tsx

@@ -0,0 +1,56 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  // Rule 50's label of last resort, in one place: the smallest size in the
+  // scale, opened right up so the face does not close into a smudge at 11px,
+  // in the heading cut and a rank below the thing it names. There is no size
+  // axis on purpose — an eyebrow that grew would be a heading.
+  base: {
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    // Regular, and stated rather than inherited. Left open, an eyebrow took
+    // the weight of whatever it was dropped into; every hand-rolled copy of
+    // this recipe pinned one, and they did not agree with each other. The
+    // tracking is what does the work at 11px — weight on top of it turns a
+    // quiet label into a second heading.
+    fontWeight: semanticTokens.fontWeightRegular,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+  },
+  // Three ranks of ink, plus the one case a label carries a warning: the
+  // heading over a destructive block has to read as the block it names.
+  secondary: {color: semanticTokens.colorTextSecondary},
+  muted: {color: semanticTokens.colorTextMuted},
+  danger: {color: semanticTokens.statusDangerText},
+});
+
+/** Ink ranks an eyebrow can take, secondary being rule 50's own. */
+export type EyebrowTone = 'secondary' | 'muted' | 'danger';
+
+/** Props for a small label that names something without competing with it. */
+export interface EyebrowProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'className'
+> {
+  readonly tone?: EyebrowTone;
+}
+
+/**
+ * Names a thing without competing with it: a card kicker, a rail heading, a
+ * metric label. It is a `span` rather than `Text`'s paragraph because an
+ * eyebrow is always placed inside somebody else's block.
+ */
+export function Eyebrow({
+  children,
+  tone = 'secondary',
+  ...props
+}: EyebrowProps) {
+  return (
+    <span {...props} {...stylex.props(styles.base, styles[tone])}>
+      {children}
+    </span>
+  );
+}

package/src/Eyebrow/index.ts

@@ -0,0 +1 @@
+export {Eyebrow, type EyebrowProps, type EyebrowTone} from './Eyebrow.js';

package/src/Field/Field.tsx

@@ -21,27 +21,48 @@ const FieldContext = createContext<FieldContextValue | null>(null);
 
 const styles = stylex.create({
   root: {display: 'grid', gap: semanticTokens.spacingXs},
+  // An eyebrow, not a title. The label names the control; the value inside the
+  // control is the thing being read, and a label set at body size in full ink
+  // competes with it down a whole column of fields. Smallest size, opened
+  // right up, heading face, second rank of ink — the way every small label in
+  // the console is set.
   label: {
     alignItems: 'baseline',
-    color: semanticTokens.colorText,
+    color: semanticTokens.colorTextSecondary,
     display: 'flex',
-    fontFamily: semanticTokens.fontFamilyBody,
-    fontSize: semanticTokens.fontSizeSm,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
     fontWeight: semanticTokens.fontWeightMedium,
     gap: semanticTokens.spacingSm,
     justifyContent: 'space-between',
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
   },
+  // An eyebrow: the smallest size, opened right up, in the heading face and the
+  // context rank of ink. "(required)" qualifies the label — it must not read as
+  // a second label, and at label size and tracking it did.
   annotation: {
     color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
     fontWeight: semanticTokens.fontWeightRegular,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
   },
+  // A description and a status are sentences, so they are set solid and lead
+  // like body copy rather than tracked out like a label.
   message: {
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
     margin: 0,
   },
   description: {color: semanticTokens.colorTextSecondary},
-  info: {color: semanticTokens.statusInfoText},
+  // A line under a field explaining the field is prose about it, not a badge
+  // on it. Colour is reserved for the two tones that mean stop; FieldStatus
+  // already said so, and the two drew the same message two ways.
+  info: {color: semanticTokens.colorTextSecondary},
   success: {color: semanticTokens.statusSuccessText},
   warning: {color: semanticTokens.statusWarningText},
   danger: {color: semanticTokens.statusDangerText},

package/src/FieldStatus/FieldStatus.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const fieldStatusDoc = {
+  name: 'FieldStatus',
+  description: 'States the validation outcome for one control.',
+  props: [
+    {name: 'children', description: 'Supplies the message text.'},
+    {name: 'tone', description: 'Selects the semantic status colour.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLParagraphElement> except aria-live, children, className, and role',
+  ],
+  example: '<FieldStatus tone="danger">Enter a release number.</FieldStatus>',
+  storyId: 'core-field-status--default',
+} satisfies ComponentDoc;

package/src/FieldStatus/FieldStatus.tsx

@@ -0,0 +1,72 @@
+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';
+
+/*
+ * The tones are ink only — a colour, never a matched `status*Surface` fill.
+ * That is deliberate and should not be "corrected" to surface pairs. `Field`
+ * renders the identical message for the identical job, as `status*Text` on
+ * whatever surface the field already sits on, and the two have to agree
+ * wherever a form uses both. `Alert` pairs surface with text because it is a
+ * block that owns its own area; a field status is one line under a control,
+ * and filling it would put a coloured strip under every input on the page.
+ *
+ * `info` takes `colorTextSecondary` rather than `statusInfoText`: a note is
+ * not an outcome. So no unmatched status surface is introduced here, and
+ * nothing reaches for `colorAccent`.
+ */
+const styles = stylex.create({
+  message: {
+    alignItems: 'baseline',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    gap: semanticTokens.spacingXs,
+    // A sentence, not a label: set solid, the way `Field` sets the identical
+    // message it renders for the identical job.
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+  // A note rather than an outcome, so it takes the neutral secondary ink
+  // instead of a status colour.
+  info: {color: semanticTokens.colorTextSecondary},
+  success: {color: semanticTokens.statusSuccessText},
+  warning: {color: semanticTokens.statusWarningText},
+  danger: {color: semanticTokens.statusDangerText},
+});
+
+/** Props for a validation message attached to one control. */
+export interface FieldStatusProps extends Omit<
+  HTMLAttributes<HTMLParagraphElement>,
+  'aria-live' | 'children' | 'className' | 'role'
+> {
+  readonly children: ReactNode;
+  readonly tone?: StatusTone;
+}
+
+/**
+ * States the outcome of validating one control. A `danger` message announces
+ * itself, because a reader who just submitted needs to hear what went wrong;
+ * every other tone is posted politely.
+ */
+export function FieldStatus({
+  children,
+  tone = 'info',
+  ...props
+}: FieldStatusProps) {
+  const failed = tone === 'danger';
+
+  return (
+    <p
+      {...props}
+      aria-live={failed ? 'assertive' : 'polite'}
+      role={failed ? 'alert' : 'status'}
+      {...stylex.props(styles.message, styles[tone])}
+    >
+      {children}
+    </p>
+  );
+}

package/src/FieldStatus/index.ts

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

package/src/FileInput/FileInput.doc.ts

@@ -0,0 +1,12 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const fileInputDoc = {
+  name: 'FileInput',
+  description: 'Chooses files and names the current selection in text.',
+  props: [{name: 'onFilesChange', description: 'Receives the chosen files.'}],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except children, className, onChange, type, and value',
+  ],
+  example: '<FileInput multiple onFilesChange={setFiles} />',
+  storyId: 'core-file-input--default',
+} satisfies ComponentDoc;