@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Markdown/parse.ts

@@ -0,0 +1,135 @@
+/** One inline run produced by the restricted Markdown parser. */
+export type InlineNode =
+  | {readonly kind: 'code'; readonly text: string}
+  | {readonly kind: 'emphasis'; readonly text: string}
+  | {readonly kind: 'link'; readonly href: string; readonly text: string}
+  | {readonly kind: 'strong'; readonly text: string}
+  | {readonly kind: 'text'; readonly text: string};
+
+/** One block produced by the restricted Markdown parser. */
+export type BlockNode =
+  | {
+      readonly kind: 'heading';
+      readonly level: 2 | 3;
+      readonly spans: readonly InlineNode[];
+    }
+  | {
+      readonly kind: 'list';
+      readonly items: readonly (readonly InlineNode[])[];
+      readonly ordered: boolean;
+    }
+  | {readonly kind: 'paragraph'; readonly spans: readonly InlineNode[]}
+  | {readonly kind: 'quote'; readonly spans: readonly InlineNode[]};
+
+// Ordered so the first match wins; `strong` must precede `emphasis`.
+const inlinePattern =
+  /(`[^`]+`)|(\[[^\]]+\]\([^)\s]+\))|(\*\*[^*]+\*\*)|(\*[^*]+\*)/u;
+
+// Only http(s) and root-relative targets survive; everything else is inert
+// text, which is what stops `javascript:` from reaching an anchor.
+function safeHref(href: string) {
+  return /^(https?:\/\/|\/)/u.test(href) ? href : undefined;
+}
+
+/** Splits one line into inline runs. */
+export function parseInline(line: string): readonly InlineNode[] {
+  const spans: InlineNode[] = [];
+  let rest = line;
+
+  while (rest !== '') {
+    const match = inlinePattern.exec(rest);
+    if (!match || match.index === undefined) {
+      spans.push({kind: 'text', text: rest});
+      break;
+    }
+
+    if (match.index > 0) {
+      spans.push({kind: 'text', text: rest.slice(0, match.index)});
+    }
+
+    const token = match[0];
+    if (token.startsWith('`')) {
+      spans.push({kind: 'code', text: token.slice(1, -1)});
+    } else if (token.startsWith('[')) {
+      const divider = token.indexOf('](');
+      const text = token.slice(1, divider);
+      const href = safeHref(token.slice(divider + 2, -1));
+      spans.push(
+        href === undefined ? {kind: 'text', text} : {href, kind: 'link', text},
+      );
+    } else if (token.startsWith('**')) {
+      spans.push({kind: 'strong', text: token.slice(2, -2)});
+    } else {
+      spans.push({kind: 'emphasis', text: token.slice(1, -1)});
+    }
+
+    rest = rest.slice(match.index + token.length);
+  }
+
+  return spans;
+}
+
+/**
+ * Parses a deliberately small Markdown subset: paragraphs, `##`/`###`
+ * headings, `-`/`1.` lists, `>` quotes, and inline code, emphasis, strong,
+ * and links. Raw HTML is never interpreted, so untrusted text stays inert.
+ */
+export function parseMarkdown(source: string): readonly BlockNode[] {
+  const blocks: BlockNode[] = [];
+  const lines = source.replace(/\r\n/gu, '\n').split('\n');
+  let index = 0;
+
+  while (index < lines.length) {
+    const line = lines[index] ?? '';
+
+    if (line.trim() === '') {
+      index += 1;
+      continue;
+    }
+
+    const heading = /^(#{2,3})\s+(.*)$/u.exec(line);
+    if (heading) {
+      blocks.push({
+        kind: 'heading',
+        level: heading[1]?.length === 2 ? 2 : 3,
+        spans: parseInline(heading[2] ?? ''),
+      });
+      index += 1;
+      continue;
+    }
+
+    if (line.startsWith('> ')) {
+      blocks.push({kind: 'quote', spans: parseInline(line.slice(2))});
+      index += 1;
+      continue;
+    }
+
+    const bullet = /^[-*]\s+(.*)$/u.exec(line);
+    const numbered = /^\d+\.\s+(.*)$/u.exec(line);
+    if (bullet || numbered) {
+      const ordered = numbered !== null;
+      const items: (readonly InlineNode[])[] = [];
+
+      while (index < lines.length) {
+        const entry = ordered
+          ? /^\d+\.\s+(.*)$/u.exec(lines[index] ?? '')
+          : /^[-*]\s+(.*)$/u.exec(lines[index] ?? '');
+        if (!entry) break;
+        items.push(parseInline(entry[1] ?? ''));
+        index += 1;
+      }
+
+      blocks.push({items, kind: 'list', ordered});
+      continue;
+    }
+
+    const paragraph: string[] = [];
+    while (index < lines.length && (lines[index] ?? '').trim() !== '') {
+      paragraph.push(lines[index] ?? '');
+      index += 1;
+    }
+    blocks.push({kind: 'paragraph', spans: parseInline(paragraph.join(' '))});
+  }
+
+  return blocks;
+}

package/src/MetadataList/MetadataList.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const metadataListDoc = {
+  name: 'MetadataList',
+  description: 'Lists labelled facts about one subject.',
+  props: [
+    {name: 'entries', description: 'Supplies the term and detail pairs.'},
+    {name: 'layout', description: 'Selects stacked or side-by-side pairing.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDListElement> except children and className',
+  ],
+  example: '<MetadataList entries={[{term: "Owner", detail: "Ada"}]} />',
+  storyId: 'core-metadata-list--default',
+} satisfies ComponentDoc;

package/src/MetadataList/MetadataList.tsx

@@ -0,0 +1,87 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  list: {
+    display: 'grid',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    margin: 0,
+  },
+  stacked: {gridTemplateColumns: '1fr'},
+  inline: {
+    alignItems: 'baseline',
+    columnGap: semanticTokens.spacingLg,
+    gridTemplateColumns: 'auto 1fr',
+  },
+  // Inline pairs hand their term and detail to the list's own grid; stacked
+  // pairs keep the label a hair above the fact it names.
+  pairInline: {display: 'contents'},
+  pairStacked: {display: 'grid', rowGap: semanticTokens.spacingXs},
+  // The term is an eyebrow: the smallest size in the scale, opened up so the
+  // display face does not close into a smudge at 11px, and set a rank below
+  // the fact it names.
+  term: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    fontWeight: semanticTokens.fontWeightRegular,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+  detail: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    margin: 0,
+  },
+});
+
+const pairs = {
+  inline: styles.pairInline,
+  stacked: styles.pairStacked,
+} as const;
+
+/** One labelled fact about the subject. */
+export interface MetadataEntry {
+  readonly detail: ReactNode;
+  readonly term: ReactNode;
+}
+
+/** Layouts a metadata list can take. */
+export type MetadataListLayout = 'inline' | 'stacked';
+
+/** Props for a list of labelled facts. */
+export interface MetadataListProps extends Omit<
+  HTMLAttributes<HTMLDListElement>,
+  'children' | 'className'
+> {
+  readonly entries: readonly MetadataEntry[];
+  readonly layout?: MetadataListLayout;
+}
+
+/**
+ * Lists labelled facts about one subject. It emits a description list, so the
+ * pairing between a term and its detail survives without visual layout.
+ */
+export function MetadataList({
+  entries,
+  layout = 'stacked',
+  ...props
+}: MetadataListProps) {
+  return (
+    <dl {...props} {...stylex.props(styles.list, styles[layout])}>
+      {entries.map(({detail, term}, index) => (
+        <div key={index} {...stylex.props(pairs[layout])}>
+          <dt {...stylex.props(styles.term)}>{term}</dt>
+          <dd {...stylex.props(styles.detail)}>{detail}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/MetadataList/index.ts

@@ -0,0 +1,6 @@
+export {
+  MetadataList,
+  type MetadataEntry,
+  type MetadataListLayout,
+  type MetadataListProps,
+} from './MetadataList.js';

package/src/MetricGrid/MetricGrid.tsx

@@ -6,38 +6,60 @@ import {semanticTokens} from '../authoring.stylex.js';
 const minimumColumnWidth = `calc(${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl})`;
 
 const styles = stylex.create({
+  // One plate, ruled by its own gaps. The grid paints itself in the hairline
+  // colour and the tiles cover it, so every interior rule is drawn once — a
+  // border on each tile would draw the shared ones twice and leave the outer
+  // edge heavier than the inside.
   root: {
+    backgroundColor: semanticTokens.borderDefault,
+    borderColor: semanticTokens.borderDefault,
+    borderRadius: semanticTokens.radiusContainer,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
     display: 'grid',
-    gap: semanticTokens.spacingLg,
+    gap: semanticTokens.borderWidth,
     gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${minimumColumnWidth}), 1fr))`,
     margin: 0,
+    overflow: 'hidden',
   },
   item: {
     backgroundColor: semanticTokens.colorSurface,
-    borderColor: semanticTokens.borderDefault,
-    borderRadius: semanticTokens.radiusContainer,
-    borderStyle: semanticTokens.borderStyle,
-    borderWidth: semanticTokens.borderWidth,
     display: 'grid',
     gap: semanticTokens.spacingXs,
     padding: semanticTokens.spacingLg,
   },
+  // Three ranks in one tile: the label names, the figure states, the detail
+  // qualifies. The label is an eyebrow, so it never competes with the figure.
   label: {
     color: semanticTokens.colorTextSecondary,
-    fontFamily: semanticTokens.fontFamilyBody,
-    fontSize: semanticTokens.fontSizeSm,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
   },
+  // A metric is a figure: mono and tabular, so a row of tiles lines its
+  // numbers up on the same stems instead of drifting by digit.
+  // A metric's headline figure is one number on its own card, not a column of
+  // them: nothing beneath it has to line up, so the mono face buys nothing and
+  // costs the page its voice — 27px of monospace reads as output, not as a
+  // figure of record. It takes the display face, like every other title here,
+  // and the tighter leading a large figure wants; a heading's 1.25 leaves a
+  // single line sitting low in its own box. No added weight either: this
+  // system's display face states a figure by its size.
   value: {
     color: semanticTokens.colorText,
-    fontFamily: semanticTokens.fontFamilyHeading,
+    fontFamily: semanticTokens.fontFamilyDisplay,
     fontSize: semanticTokens.fontSizeXl,
-    fontWeight: semanticTokens.fontWeightStrong,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingTitle,
+    lineHeight: 1.15,
     margin: 0,
   },
   detail: {
     color: semanticTokens.colorTextMuted,
     fontFamily: semanticTokens.fontFamilyBody,
     fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
     margin: 0,
   },
 });

package/src/MobileNav/MobileNav.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const mobileNavDoc = {
+  name: 'MobileNav',
+  description: 'Holds navigation behind a trigger on narrow viewports.',
+  props: [
+    {name: 'children', description: 'Supplies the navigation content.'},
+    {name: 'closeLabel', description: 'Names the dismiss control.'},
+    {name: 'label', description: 'Names the trigger and the drawer.'},
+    {name: 'title', description: 'Replaces the drawer heading text.'},
+  ],
+  inheritedProps: ['None; MobileNav owns its trigger and drawer'],
+  example: '<MobileNav label="Open navigation">{menu}</MobileNav>',
+  storyId: 'core-mobile-nav--default',
+} satisfies ComponentDoc;

package/src/MobileNav/MobileNav.tsx

@@ -0,0 +1,169 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, useState, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {useFocusTrap} from '../hooks/useFocusTrap.js';
+import {useScrollLock} from '../hooks/useScrollLock.js';
+import {Icon} from '../Icon/index.js';
+import {IconButton} from '../IconButton/index.js';
+import {Layer} from '../Layer/index.js';
+
+// Wide enough for a two-word destination and its glyph, narrow enough that the
+// page behind it stays visible. Built from the scale, not written as a length.
+const drawerMaxWidth = `calc(11 * ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  // The scrim is the one token that says "the page behind this is out of
+  // reach". `overlayActive` says something else entirely — it is the wash a
+  // row wears while a finger is down on it, 7% ink, which leaves the page
+  // fully legible and fully clickable-looking behind an open drawer.
+  scrim: {
+    backgroundColor: semanticTokens.colorScrim,
+    display: 'flex',
+    inset: 0,
+    position: 'fixed',
+  },
+  // A floating surface: elevation and no border, because stacking both draws
+  // the same line twice.
+  drawer: {
+    backgroundColor: semanticTokens.colorSurface,
+    borderEndEndRadius: semanticTokens.radiusPage,
+    borderStartEndRadius: semanticTokens.radiusPage,
+    borderStyle: 'none',
+    boxShadow: semanticTokens.elevationHigh,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    maxWidth: drawerMaxWidth,
+    outlineStyle: 'none',
+    overflowY: 'auto',
+    padding: semanticTokens.spacingLg,
+    rowGap: semanticTokens.spacingLg,
+    width: '85%',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  // The drawer's own masthead, parted from the destinations by a rule.
+  header: {
+    alignItems: 'center',
+    borderBlockEndColor: semanticTokens.borderStrong,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    columnGap: semanticTokens.spacingSm,
+    display: 'flex',
+    justifyContent: 'space-between',
+    paddingBlockEnd: semanticTokens.spacingMd,
+  },
+  title: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeLg,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingHeading,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+  },
+});
+
+/** Props for the navigation drawer used on narrow viewports. */
+export interface MobileNavProps {
+  readonly children: ReactNode;
+  readonly closeLabel?: string;
+  readonly label: string;
+  readonly title?: ReactNode;
+}
+
+/**
+ * Holds navigation behind a trigger on narrow viewports. It owns its open
+ * state and traps focus inside the drawer while it is open.
+ */
+export function MobileNav({
+  children,
+  closeLabel = 'Close navigation',
+  label,
+  title,
+}: MobileNavProps) {
+  const [open, setOpen] = useState(false);
+  const [drawer, setDrawer] = useState<HTMLDivElement | null>(null);
+  const titleId = useId();
+
+  useFocusTrap(drawer, open);
+  useScrollLock(open);
+
+  return (
+    <>
+      <IconButton
+        aria-expanded={open}
+        aria-label={label}
+        onClick={() => {
+          setOpen(true);
+        }}
+        variant="ghost"
+      >
+        <Icon>
+          <path
+            d="M4 7h16M4 12h16M4 17h16"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+          />
+        </Icon>
+      </IconButton>
+      {open ? (
+        <Layer>
+          <div
+            onMouseDown={(event) => {
+              if (event.target === event.currentTarget) {
+                setOpen(false);
+              }
+            }}
+            {...stylex.props(styles.scrim)}
+          >
+            <div
+              aria-labelledby={titleId}
+              aria-modal="true"
+              onKeyDown={(event) => {
+                if (event.key === 'Escape') {
+                  setOpen(false);
+                }
+              }}
+              ref={setDrawer}
+              role="dialog"
+              {...stylex.props(styles.drawer, scrolling.region)}
+              tabIndex={-1}
+            >
+              <div {...stylex.props(styles.header)}>
+                <p id={titleId} {...stylex.props(styles.title)}>
+                  {title ?? label}
+                </p>
+                <IconButton
+                  aria-label={closeLabel}
+                  onClick={() => {
+                    setOpen(false);
+                  }}
+                  variant="ghost"
+                >
+                  <Icon>
+                    <path
+                      d="m6 6 12 12M18 6 6 18"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                    />
+                  </Icon>
+                </IconButton>
+              </div>
+              {children}
+            </div>
+          </div>
+        </Layer>
+      ) : null}
+    </>
+  );
+}

package/src/MobileNav/index.ts

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

package/src/MoreMenu/MoreMenu.doc.ts

@@ -0,0 +1,19 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const moreMenuDoc = {
+  name: 'MoreMenu',
+  description: 'Collects secondary actions behind a self-managed trigger.',
+  props: [
+    {name: 'alignment', description: 'Lines the menu up along the cross axis.'},
+    {name: 'children', description: 'Supplies the menu items.'},
+    {name: 'label', description: 'Names the trigger and the menu.'},
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the trigger.',
+    },
+  ],
+  inheritedProps: ['None; MoreMenu owns its trigger and menu'],
+  example:
+    '<MoreMenu label="More actions"><DropdownMenuItem>Archive</DropdownMenuItem></MoreMenu>',
+  storyId: 'core-more-menu--default',
+} satisfies ComponentDoc;

package/src/MoreMenu/MoreMenu.tsx

@@ -0,0 +1,67 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, useState, type ReactNode} from 'react';
+
+import {DropdownMenu} from '../DropdownMenu/index.js';
+import type {Alignment, Placement} from '../hooks/useAnchoredPosition.js';
+import {Icon} from '../Icon/index.js';
+import {IconButton} from '../IconButton/index.js';
+
+const styles = stylex.create({
+  anchor: {display: 'inline-flex'},
+});
+
+/** Props for the self-managed overflow menu. */
+export interface MoreMenuProps {
+  readonly alignment?: Alignment;
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly placement?: Placement;
+}
+
+/**
+ * Collects secondary actions behind one trigger and owns its own open state,
+ * so a caller that has no other reason to hold state does not grow one.
+ */
+export function MoreMenu({
+  alignment,
+  children,
+  label,
+  placement,
+}: MoreMenuProps) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <span ref={anchorRef} {...stylex.props(styles.anchor)}>
+        <IconButton
+          aria-expanded={open}
+          aria-haspopup="menu"
+          aria-label={label}
+          onClick={() => {
+            setOpen((value) => !value);
+          }}
+          variant="ghost"
+        >
+          <Icon>
+            <circle cx="5" cy="12" r="1.75" />
+            <circle cx="12" cy="12" r="1.75" />
+            <circle cx="19" cy="12" r="1.75" />
+          </Icon>
+        </IconButton>
+      </span>
+      <DropdownMenu
+        {...(alignment ? {alignment} : {})}
+        anchorRef={anchorRef}
+        label={label}
+        onDismiss={() => {
+          setOpen(false);
+        }}
+        open={open}
+        {...(placement ? {placement} : {})}
+      >
+        {children}
+      </DropdownMenu>
+    </>
+  );
+}

package/src/MoreMenu/index.ts

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

package/src/MultiSelector/MultiSelector.doc.ts

@@ -0,0 +1,23 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const multiSelectorDoc = {
+  name: 'MultiSelector',
+  description: 'Chooses several options through a typeahead.',
+  props: [
+    {name: 'emptyMessage', description: 'States that nothing matched.'},
+    {name: 'label', description: 'Names the search field.'},
+    {name: 'onValueChange', description: 'Receives the next set of values.'},
+    {name: 'options', description: 'Supplies every selectable option.'},
+    {
+      name: 'removeLabel',
+      description: 'Builds the name of each remove control.',
+    },
+    {name: 'value', description: 'Controls the current set of values.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, defaultValue, and onChange',
+  ],
+  example:
+    '<MultiSelector label="Owners" onValueChange={setOwners} options={people} value={owners} />',
+  storyId: 'core-multi-selector--default',
+} satisfies ComponentDoc;