@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/TopNavMegaMenu/TopNavMegaMenu.tsx

@@ -0,0 +1,251 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useRef,
+  useState,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Heading} from '../Heading/index.js';
+import {Icon} from '../Icon/index.js';
+import {Link} from '../navigation/index.js';
+import {Popover} from '../Popover/index.js';
+import {Text} from '../Text/index.js';
+
+// The trigger wears the same mark as the destinations beside it: two
+// hairlines at the inline-start edge, hinted on hover and claimed when open.
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const hoverMarkHeight = '40%';
+const openMarkHeight = '72%';
+const columnMinWidth = `calc(7 * ${semanticTokens.spacing2xl})`;
+const panelMaxWidth = `calc(30 * ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  anchor: {display: 'inline-flex'},
+  trigger: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorTextSecondary,
+    columnGap: semanticTokens.spacingXs,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    '::before': {
+      content: '',
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      transitionDuration: `${semanticTokens.durationFast}, ${semanticTokens.durationModerate}`,
+      transitionProperty: 'background-color, height',
+      transitionTimingFunction: semanticTokens.easingStandard,
+      width: markWidth,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  closed: {
+    '::before': {
+      backgroundColor: semanticTokens.borderStrong,
+      height: {default: 0, ':hover': hoverMarkHeight},
+    },
+    ':hover': {color: semanticTokens.colorText},
+  },
+  open: {
+    color: semanticTokens.colorText,
+    '::before': {
+      backgroundColor: semanticTokens.colorAccent,
+      height: openMarkHeight,
+    },
+  },
+  marker: {
+    alignItems: 'center',
+    display: 'inline-flex',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'transform',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  markerOpen: {transform: 'rotate(180deg)'},
+  panel: {
+    display: 'grid',
+    gap: semanticTokens.spacingXl,
+    gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${columnMinWidth}), 1fr))`,
+    maxWidth: panelMaxWidth,
+  },
+  column: {
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: semanticTokens.borderWidth,
+  },
+  // The same eyebrow the rail's section headings take: smallest size, opened
+  // right up, display face, second rank of ink.
+  columnTitle: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeXs,
+    fontSynthesis: 'none',
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+    paddingBlockEnd: semanticTokens.spacingXs,
+    paddingInlineEnd: 0,
+    paddingInlineStart: semanticTokens.spacingMd,
+  },
+  // A well sunk into the panel it sits in, so it takes the inner radius and
+  // wears its hover as a wash laid over the fill rather than replacing it.
+  card: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusInner,
+    display: 'flex',
+    flexDirection: 'column',
+    padding: semanticTokens.spacingMd,
+    rowGap: semanticTokens.spacingXs,
+    textDecorationLine: 'none',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, background-image',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {
+      backgroundImage: `linear-gradient(${semanticTokens.colorOverlayHover}, ${semanticTokens.colorOverlayHover})`,
+    },
+  },
+});
+
+/** One titled column inside a mega menu. */
+export interface MegaMenuColumn {
+  readonly items: ReactNode;
+  readonly title?: string;
+}
+
+/** Props for the banner's panelled menu. */
+export interface TopNavMegaMenuProps {
+  readonly columns: readonly MegaMenuColumn[];
+  readonly featured?: ReactNode;
+  readonly label: string;
+}
+
+/**
+ * A wide banner panel holding several columns of destinations. Like
+ * `TopNavMenu` it is a disclosure, not a `menu`: everything inside navigates
+ * somewhere rather than running a command.
+ */
+export function TopNavMegaMenu({
+  columns,
+  featured,
+  label,
+}: TopNavMegaMenuProps) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <span ref={anchorRef} {...stylex.props(styles.anchor)}>
+        <button
+          aria-expanded={open}
+          onClick={() => {
+            setOpen((value) => !value);
+          }}
+          {...stylex.props(styles.trigger, open ? styles.open : styles.closed)}
+          type="button"
+        >
+          {label}
+          <span
+            aria-hidden="true"
+            {...stylex.props(styles.marker, open && styles.markerOpen)}
+          >
+            <Icon size="sm">
+              <path
+                d="m6 9 6 6 6-6"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </Icon>
+          </span>
+        </button>
+      </span>
+      <Popover
+        alignment="start"
+        anchorRef={anchorRef}
+        aria-label={label}
+        onDismiss={() => {
+          setOpen(false);
+        }}
+        open={open}
+        role="group"
+      >
+        <div {...stylex.props(styles.panel)}>
+          {columns.map((column, index) => (
+            <div key={column.title ?? index} {...stylex.props(styles.column)}>
+              {column.title === undefined ? null : (
+                <p {...stylex.props(styles.columnTitle)}>{column.title}</p>
+              )}
+              {column.items}
+            </div>
+          ))}
+          {featured}
+        </div>
+      </Popover>
+    </>
+  );
+}
+
+/** Props for the promoted entry inside a mega menu. */
+export interface TopNavMegaMenuFeaturedCardProps extends Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  'children' | 'className' | 'href' | 'media' | 'title'
+> {
+  readonly description?: ReactNode;
+  readonly href: string;
+  readonly media?: ReactNode;
+  readonly title: ReactNode;
+}
+
+/**
+ * The one promoted destination in a mega menu. It is a single link, so the
+ * whole card is one tab stop — never put another control inside it.
+ */
+export function TopNavMegaMenuFeaturedCard({
+  description,
+  href,
+  media,
+  title,
+  ...props
+}: TopNavMegaMenuFeaturedCardProps) {
+  return (
+    <Link {...props} href={href} {...stylex.props(styles.card)}>
+      {media}
+      <Heading level={3} size="subsection">
+        {title}
+      </Heading>
+      {description === undefined ? null : (
+        <Text size="sm" tone="secondary">
+          {description}
+        </Text>
+      )}
+    </Link>
+  );
+}

package/src/TopNavMegaMenu/index.ts

@@ -0,0 +1,7 @@
+export {
+  TopNavMegaMenu,
+  TopNavMegaMenuFeaturedCard,
+  type MegaMenuColumn,
+  type TopNavMegaMenuFeaturedCardProps,
+  type TopNavMegaMenuProps,
+} from './TopNavMegaMenu.js';

package/src/TopNavMenu/TopNavMenu.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const topNavMenuDoc = {
+  name: 'TopNavMenu',
+  description: 'A grouped disclosure menu inside the page banner.',
+  props: [
+    {
+      name: 'alignment',
+      description: 'Lines the panel up along the cross axis.',
+    },
+    {name: 'children', description: 'Supplies the destinations.'},
+    {name: 'label', description: 'Names the trigger and the panel.'},
+    {
+      name: 'placement',
+      description: 'Selects the preferred side of the trigger.',
+    },
+  ],
+  inheritedProps: ['None; TopNavMenu owns its trigger and panel'],
+  example:
+    '<TopNavMenu label="Product"><NavItem href="/a">A</NavItem></TopNavMenu>',
+  storyId: 'core-top-nav-menu--default',
+} satisfies ComponentDoc;

package/src/TopNavMenu/TopNavMenu.tsx

@@ -0,0 +1,166 @@
+import * as stylex from '@stylexjs/stylex';
+import {useRef, useState, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {focusableElements} from '../hooks/focusableSelector.js';
+import {useListFocus} from '../hooks/useListFocus.js';
+import {Icon} from '../Icon/index.js';
+import {Popover} from '../Popover/index.js';
+import type {Alignment, Placement} from '../hooks/useAnchoredPosition.js';
+
+// The trigger wears the same mark as the destinations beside it: two
+// hairlines at the inline-start edge, hinted on hover and claimed when open.
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const hoverMarkHeight = '40%';
+const openMarkHeight = '72%';
+const panelMinWidth = `calc(8 * ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  anchor: {display: 'inline-flex'},
+  trigger: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorTextSecondary,
+    columnGap: semanticTokens.spacingXs,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    '::before': {
+      content: '',
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      transitionDuration: `${semanticTokens.durationFast}, ${semanticTokens.durationModerate}`,
+      transitionProperty: 'background-color, height',
+      transitionTimingFunction: semanticTokens.easingStandard,
+      width: markWidth,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  closed: {
+    '::before': {
+      backgroundColor: semanticTokens.borderStrong,
+      height: {default: 0, ':hover': hoverMarkHeight},
+    },
+    ':hover': {color: semanticTokens.colorText},
+  },
+  open: {
+    color: semanticTokens.colorText,
+    '::before': {
+      backgroundColor: semanticTokens.colorAccent,
+      height: openMarkHeight,
+    },
+  },
+  marker: {
+    alignItems: 'center',
+    display: 'inline-flex',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'transform',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  markerOpen: {transform: 'rotate(180deg)'},
+  panel: {
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: panelMinWidth,
+    // A run of destinations tiles one hairline apart, as it does in the rail.
+    rowGap: semanticTokens.borderWidth,
+  },
+});
+
+/** Props for a grouped menu inside the page banner. */
+export interface TopNavMenuProps {
+  readonly alignment?: Alignment;
+  readonly children: ReactNode;
+  readonly label: string;
+  readonly placement?: Placement;
+}
+
+/**
+ * A banner menu that owns its open state. It is a disclosure rather than a
+ * `menu`: the panel holds links to elsewhere, and calling those `menuitem`
+ * would promise a command that runs here.
+ */
+export function TopNavMenu({
+  alignment = 'start',
+  children,
+  label,
+  placement = 'bottom',
+}: TopNavMenuProps) {
+  const anchorRef = useRef<HTMLSpanElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState(false);
+  const {onKeyDown} = useListFocus(panelRef, {orientation: 'vertical'});
+
+  return (
+    <>
+      <span ref={anchorRef} {...stylex.props(styles.anchor)}>
+        <button
+          aria-expanded={open}
+          onClick={() => {
+            setOpen((value) => !value);
+          }}
+          {...stylex.props(styles.trigger, open ? styles.open : styles.closed)}
+          type="button"
+        >
+          {label}
+          <span
+            aria-hidden="true"
+            {...stylex.props(styles.marker, open && styles.markerOpen)}
+          >
+            <Icon size="sm">
+              <path
+                d="m6 9 6 6 6-6"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </Icon>
+          </span>
+        </button>
+      </span>
+      <Popover
+        alignment={alignment}
+        anchorRef={anchorRef}
+        aria-label={label}
+        onDismiss={() => {
+          setOpen(false);
+        }}
+        open={open}
+        placement={placement}
+        role="group"
+      >
+        <div
+          onKeyDown={onKeyDown}
+          ref={(node) => {
+            panelRef.current = node;
+            if (node) {
+              focusableElements(node)[0]?.focus({preventScroll: true});
+            }
+          }}
+          {...stylex.props(styles.panel)}
+        >
+          {children}
+        </div>
+      </Popover>
+    </>
+  );
+}

package/src/TopNavMenu/index.ts

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

package/src/TreeList/TreeList.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const treeListDoc = {
+  name: 'TreeList',
+  description: 'Presents a collapsible hierarchy as one tab stop.',
+  props: [
+    {name: 'expandedIds', description: 'Controls which branches are open.'},
+    {name: 'label', description: 'Names the tree for assistive technology.'},
+    {name: 'nodes', description: 'Supplies the hierarchy in reading order.'},
+    {name: 'onExpandedChange', description: 'Receives the next open branches.'},
+    {name: 'onSelect', description: 'Receives the id of the chosen node.'},
+    {name: 'selectedId', description: 'Marks which node is selected.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLUListElement> except aria-label, children, className, onSelect, and role',
+  ],
+  example:
+    '<TreeList expandedIds={open} label="Files" nodes={tree} onExpandedChange={setOpen} />',
+  storyId: 'core-tree-list--default',
+} satisfies ComponentDoc;