@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,122 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {useClipboard} from '../hooks/useClipboard.js';
+import {Button} from '../Button/index.js';
+
+// The gutter the copy control needs. It is not the control's height — the
+// control is a Button carrying a word, and the word changes: "Copy" becomes
+// "Copied" the moment it is pressed, and a translation may be longer than
+// both. Measuring it as one small square left a long line running under the
+// button, which is what a gutter exists to prevent. Six steps of the outer
+// scale clears the longer label at either density with room to spare, and it
+// is still written as a relationship rather than as a pixel count.
+const copyGutter = `calc(3 * ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  // The well sinks below the surface it sits on, so it needs no border of
+  // its own: the fill already draws the edge.
+  frame: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusInner,
+    borderStyle: 'none',
+    display: 'grid',
+    position: 'relative',
+  },
+  pre: {
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+    marginBlock: 0,
+    overflowX: 'auto',
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInlineStart: semanticTokens.spacingMd,
+    // The copy control floats over this box, so the source needs a gutter to
+    // end in rather than a symmetric padding to run under. Without it a single
+    // long line — an install command is always one long line — disappeared
+    // beneath the button, and the block read as truncated.
+    paddingInlineEnd: copyGutter,
+  },
+  code: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+  // A wrapped line has to look like a continuation, not like the next line of
+  // source. The hanging indent is what says so: the first line starts at the
+  // gutter and every line it wraps onto is set in by one step.
+  wrap: {
+    overflowWrap: 'anywhere',
+    paddingInlineStart: `calc(${semanticTokens.spacingMd} + ${semanticTokens.spacingLg})`,
+    textIndent: `calc(-1 * ${semanticTokens.spacingLg})`,
+    whiteSpace: 'pre-wrap',
+  },
+  copy: {
+    insetBlockStart: semanticTokens.spacingXs,
+    insetInlineEnd: semanticTokens.spacingXs,
+    position: 'absolute',
+  },
+});
+
+/** Props for a block of preformatted source. */
+export interface CodeBlockProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly code: string;
+  readonly copiedLabel?: string;
+  readonly copyLabel?: string;
+  readonly language?: string;
+  /**
+   * Wraps long lines instead of scrolling them. Worth setting whenever a line
+   * can outrun the column — an install command or a `<link>` tag always does,
+   * and source that leaves the viewport is source a reader copies wrongly.
+   */
+  readonly wrap?: boolean;
+}
+
+/**
+ * Shows a block of source. The copy control reports its own result, so a
+ * reader knows the copy happened without watching the clipboard.
+ */
+export function CodeBlock({
+  code,
+  copiedLabel = 'Copied',
+  copyLabel = 'Copy',
+  language,
+  wrap = false,
+  ...props
+}: CodeBlockProps) {
+  const {copied, copy} = useClipboard();
+
+  return (
+    <div {...props} {...stylex.props(styles.frame)}>
+      <pre {...stylex.props(styles.pre, scrolling.region, wrap && styles.wrap)}>
+        <code
+          {...(language === undefined ? {} : {'data-language': language})}
+          {...stylex.props(styles.code)}
+        >
+          {code}
+        </code>
+      </pre>
+      <span {...stylex.props(styles.copy)}>
+        <Button
+          onClick={() => {
+            void copy(code);
+          }}
+          size="sm"
+          variant="secondary"
+        >
+          {copied ? copiedLabel : copyLabel}
+        </Button>
+      </span>
+    </div>
+  );
+}

package/src/CodeBlock/index.ts

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

package/src/Collapsible/Collapsible.doc.ts

@@ -0,0 +1,18 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const collapsibleDoc = {
+  name: 'Collapsible',
+  description: 'Folds a section away behind its own heading.',
+  props: [
+    {name: 'children', description: 'Supplies the panel content.'},
+    {name: 'defaultOpen', description: 'Sets the initial uncontrolled state.'},
+    {name: 'label', description: 'Names the section on the trigger.'},
+    {name: 'onOpenChange', description: 'Receives the next open state.'},
+    {name: 'open', description: 'Controls whether the panel is shown.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and onChange',
+  ],
+  example: '<Collapsible label="Advanced">…</Collapsible>',
+  storyId: 'core-collapsible--default',
+} satisfies ComponentDoc;

package/src/Collapsible/Collapsible.tsx

@@ -0,0 +1,165 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, useState, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Icon} from '../Icon/index.js';
+
+// The panel grows from a closed track to an open one. `grid-template-rows` is
+// the only height that interpolates, so the reveal is a grid, not a `height`.
+const reveal = stylex.keyframes({
+  from: {gridTemplateRows: '0fr'},
+  to: {gridTemplateRows: '1fr'},
+});
+
+const styles = stylex.create({
+  region: {
+    display: 'grid',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+  },
+  trigger: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorText,
+    cursor: 'pointer',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    fontWeight: semanticTokens.fontWeightMedium,
+    gap: semanticTokens.spacingSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingSm,
+    paddingInline: semanticTokens.spacingSm,
+    textAlign: 'start',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled)': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+    },
+  },
+  marker: {
+    color: semanticTokens.colorTextSecondary,
+    flexShrink: 0,
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'transform',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  markerOpen: {transform: 'rotate(90deg)'},
+  label: {flexGrow: 1, minWidth: 0},
+  // The rule the indent hangs off. An indent alone leaves the revealed body
+  // floating beside its own heading; the hairline says the run belongs to the
+  // section above it, which is how the console draws a second level.
+  panel: {
+    borderInlineStartColor: semanticTokens.borderDefault,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.borderWidth,
+    paddingInlineStart: semanticTokens.spacingLg,
+  },
+  reveal: {
+    animationDuration: semanticTokens.durationModerate,
+    animationName: {
+      default: reveal,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingEmphasized,
+    display: 'grid',
+    gridTemplateRows: '1fr',
+  },
+  revealContent: {minHeight: 0, overflow: 'hidden'},
+});
+
+type SharedCollapsibleProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'onChange'
+> & {
+  readonly children: ReactNode;
+  readonly label: ReactNode;
+  readonly onOpenChange?: (open: boolean) => void;
+};
+
+type ControlledCollapsibleProps = SharedCollapsibleProps & {
+  readonly defaultOpen?: never;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly open: boolean;
+};
+
+type UncontrolledCollapsibleProps = SharedCollapsibleProps & {
+  readonly defaultOpen?: boolean;
+  readonly open?: never;
+};
+
+/** Props for a section that can be folded away. */
+export type CollapsibleProps =
+  ControlledCollapsibleProps | UncontrolledCollapsibleProps;
+
+/**
+ * Folds a section away behind its own heading. The panel stays in the DOM
+ * and is hidden, so a find-in-page match still reveals where the text lives.
+ */
+export function Collapsible({
+  children,
+  defaultOpen = false,
+  label,
+  onOpenChange,
+  open,
+  ...props
+}: CollapsibleProps) {
+  const panelId = useId();
+  const triggerId = useId();
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isOpen = open ?? internalOpen;
+
+  return (
+    <div {...props} {...stylex.props(styles.region)}>
+      <button
+        aria-controls={panelId}
+        aria-expanded={isOpen}
+        id={triggerId}
+        onClick={() => {
+          const next = !isOpen;
+          if (open === undefined) {
+            setInternalOpen(next);
+          }
+          onOpenChange?.(next);
+        }}
+        {...stylex.props(styles.trigger)}
+        type="button"
+      >
+        <span {...stylex.props(styles.marker, isOpen && styles.markerOpen)}>
+          <Icon>
+            <path
+              d="m9 6 6 6-6 6"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+            />
+          </Icon>
+        </span>
+        <span {...stylex.props(styles.label)}>{label}</span>
+      </button>
+      <div
+        aria-labelledby={triggerId}
+        hidden={!isOpen}
+        id={panelId}
+        role="region"
+        {...stylex.props(styles.panel)}
+      >
+        <div {...stylex.props(styles.reveal)}>
+          <div {...stylex.props(styles.revealContent)}>{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/Collapsible/index.ts

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

package/src/CommandPalette/CommandPalette.doc.ts

@@ -0,0 +1,19 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const commandPaletteDoc = {
+  name: 'CommandPalette',
+  description: 'Runs a command by searching for it by name.',
+  props: [
+    {name: 'commands', description: 'Supplies every runnable command.'},
+    {name: 'emptyMessage', description: 'States that nothing matched.'},
+    {name: 'label', description: 'Names the palette for assistive technology.'},
+    {name: 'onDismiss', description: 'Runs on Escape or an outside click.'},
+    {name: 'onRun', description: 'Receives the command the reader chose.'},
+    {name: 'open', description: 'Controls whether the palette renders.'},
+    {name: 'placeholder', description: 'Names and hints at the search field.'},
+  ],
+  inheritedProps: ['None; CommandPalette owns its modal surface'],
+  example:
+    '<CommandPalette commands={commands} onDismiss={close} onRun={run} open={open} />',
+  storyId: 'core-command-palette--default',
+} satisfies ComponentDoc;

package/src/CommandPalette/CommandPalette.tsx

@@ -0,0 +1,326 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useEffect,
+  useId,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {Icon} from '../Icon/index.js';
+import {useInternationalization} from '../i18n/index.js';
+import {Overlay} from '../Overlay/index.js';
+
+// About twenty spacing steps wide: long command names read on one line.
+const surfaceWidth = `calc(20 * ${semanticTokens.spacing2xl})`;
+
+const markWidth = `calc(2 * ${semanticTokens.borderWidth})`;
+const markHeight = '64%';
+
+const styles = stylex.create({
+  surface: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationHigh,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    maxHeight: '70vh',
+    maxWidth: surfaceWidth,
+    overflow: 'hidden',
+    width: '100%',
+  },
+  // The query line is set bare on the paper with one rule under it, not in a
+  // second box: a field inside a floating panel draws the panel's edge twice.
+  // The rule is the strong hairline, because it is the only thing separating
+  // what the reader is typing from what the typing is turning up.
+  search: {
+    alignItems: 'center',
+    borderBlockEndColor: semanticTokens.borderStrong,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    gap: semanticTokens.spacingMd,
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  input: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorText,
+    flexGrow: 1,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    minWidth: 0,
+    padding: 0,
+    '::placeholder': {color: semanticTokens.colorTextMuted},
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  list: {
+    listStyleType: 'none',
+    marginBlock: 0,
+    overflowY: 'auto',
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInlineStart: 0,
+  },
+  // The eyebrow: display face, smallest size, opened right up, secondary ink.
+  // It names the group without competing with the commands inside it, and the
+  // mincho line is what marks it as a caption rather than a shouted heading —
+  // which is why it is not set in capitals as well.
+  groupLabel: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeXs,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    marginBlock: 0,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  // A command that is merely available is set in the second rank; the one the
+  // keys are pointing at rises to the first. The wash alone would say it, but
+  // a wash this quiet needs the ink to agree with it.
+  option: {
+    alignItems: 'center',
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'flex',
+    gap: semanticTokens.spacingMd,
+    justifyContent: 'space-between',
+    paddingBlock: semanticTokens.spacingSm,
+    paddingInline: semanticTokens.spacingLg,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  idle: {
+    ':hover': {
+      backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
+    },
+  },
+  // Focus never leaves the field, so the row the keys point at has to say so
+  // on its own: the wash, the first rank of ink, and the bookmark at the
+  // inline-start edge — never a filled blue bar, which would be the only
+  // block of colour on the page.
+  active: {
+    backgroundColor: semanticTokens.colorOverlayHover,
+    color: semanticTokens.colorText,
+    '::before': {
+      backgroundColor: semanticTokens.colorAccent,
+      content: '',
+      height: markHeight,
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+      width: markWidth,
+    },
+  },
+  label: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+  },
+  // A keyboard hint is a figure, and a key cap is a well in the paper: mono
+  // and tabular so a column of them lines up down the list, on the sunken
+  // fill so it reads as something to press rather than as more prose.
+  shortcut: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusInner,
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeXs,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    paddingInline: semanticTokens.spacingXs,
+    whiteSpace: 'nowrap',
+  },
+  empty: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    marginBlock: 0,
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+  },
+});
+
+/** One runnable command. */
+export interface Command {
+  readonly group?: string;
+  readonly id: string;
+  readonly label: string;
+  readonly shortcut?: string;
+}
+
+/** Props for the searchable command list. */
+export interface CommandPaletteProps {
+  readonly commands: readonly Command[];
+  readonly emptyMessage?: ReactNode;
+  readonly label?: string;
+  readonly onDismiss: () => void;
+  readonly onRun: (command: Command) => void;
+  readonly open: boolean;
+  readonly placeholder?: string;
+}
+
+/**
+ * Runs a command by name. Focus stays in the search field and
+ * `aria-activedescendant` names the highlighted command, so typing and
+ * choosing never fight each other for focus.
+ */
+export function CommandPalette({
+  commands,
+  emptyMessage,
+  label = 'Command palette',
+  onDismiss,
+  onRun,
+  open,
+  placeholder,
+}: CommandPaletteProps) {
+  const {messages} = useInternationalization();
+  const resolvedPlaceholder = placeholder ?? messages.commandPalettePlaceholder;
+  const listboxId = useId();
+  const optionPrefix = useId();
+  const [query, setQuery] = useState('');
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  const matches = commands.filter((command) =>
+    command.label.toLowerCase().includes(query.toLowerCase()),
+  );
+  const active = matches[activeIndex];
+
+  useEffect(() => {
+    if (!open) {
+      setQuery('');
+      setActiveIndex(0);
+    }
+  }, [open]);
+
+  function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (matches.length > 0) {
+        const step = event.key === 'ArrowDown' ? 1 : -1;
+        setActiveIndex(
+          (index) => (index + step + matches.length) % matches.length,
+        );
+      }
+      return;
+    }
+    if (event.key === 'Home' || event.key === 'End') {
+      if (matches.length === 0) {
+        return;
+      }
+      event.preventDefault();
+      setActiveIndex(event.key === 'Home' ? 0 : matches.length - 1);
+      return;
+    }
+    if (event.key === 'Enter' && active) {
+      event.preventDefault();
+      onRun(active);
+    }
+  }
+
+  let lastGroup: string | undefined;
+
+  return (
+    <Overlay onDismiss={onDismiss} open={open}>
+      <div aria-label={label} role="dialog" {...stylex.props(styles.surface)}>
+        <div {...stylex.props(styles.search)}>
+          {/* The glass names the line as a search without a word of chrome. */}
+          <Icon size="md" tone="muted">
+            <path
+              d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14Zm5 12 4 4"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+            />
+          </Icon>
+          <input
+            aria-activedescendant={
+              active ? `${optionPrefix}-${activeIndex}` : undefined
+            }
+            aria-autocomplete="list"
+            aria-controls={listboxId}
+            aria-expanded
+            aria-label={resolvedPlaceholder}
+            autoComplete="off"
+            onChange={(event) => {
+              setQuery(event.currentTarget.value);
+              setActiveIndex(0);
+            }}
+            onKeyDown={handleKeyDown}
+            placeholder={resolvedPlaceholder}
+            role="combobox"
+            value={query}
+            {...stylex.props(styles.input)}
+            type="text"
+          />
+        </div>
+        <ul
+          id={listboxId}
+          role="listbox"
+          {...stylex.props(styles.list, scrolling.region)}
+        >
+          {matches.map((command, index) => {
+            const showGroup =
+              command.group !== undefined && command.group !== lastGroup;
+            lastGroup = command.group;
+
+            return (
+              <li key={command.id} role="none">
+                {showGroup ? (
+                  <p aria-hidden="true" {...stylex.props(styles.groupLabel)}>
+                    {command.group}
+                  </p>
+                ) : null}
+                <div
+                  aria-selected={index === activeIndex}
+                  id={`${optionPrefix}-${index}`}
+                  onClick={() => {
+                    onRun(command);
+                  }}
+                  role="option"
+                  {...stylex.props(
+                    styles.option,
+                    index === activeIndex ? styles.active : styles.idle,
+                  )}
+                >
+                  <span {...stylex.props(styles.label)}>{command.label}</span>
+                  {command.shortcut === undefined ? null : (
+                    <kbd {...stylex.props(styles.shortcut)}>
+                      {command.shortcut}
+                    </kbd>
+                  )}
+                </div>
+              </li>
+            );
+          })}
+        </ul>
+        {matches.length === 0 ? (
+          // A listbox may own nothing but options, so the notice sits beside
+          // it and announces itself instead.
+          <p role="status" {...stylex.props(styles.empty)}>
+            {emptyMessage ?? messages.commandPaletteEmpty}
+          </p>
+        ) : null}
+      </div>
+    </Overlay>
+  );
+}

package/src/CommandPalette/index.ts

@@ -0,0 +1,5 @@
+export {
+  CommandPalette,
+  type Command,
+  type CommandPaletteProps,
+} from './CommandPalette.js';

package/src/ComplexSelector/ComplexSelector.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const complexSelectorDoc = {
+  name: 'ComplexSelector',
+  description: 'Chooses one option from grouped lists.',
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled value.'},
+    {name: 'groups', description: 'Supplies the named groups of options.'},
+    {name: 'onValueChange', description: 'Receives the newly chosen value.'},
+    {
+      name: 'placeholder',
+      description: 'Adds a disabled prompt as the first entry.',
+    },
+    {name: 'value', description: 'Controls the current value.'},
+  ],
+  inheritedProps: [
+    'SelectHTMLAttributes<HTMLSelectElement> except children, className, defaultValue, onChange, and value',
+  ],
+  example:
+    '<ComplexSelector groups={teams} onValueChange={setOwner} value={owner} />',
+  storyId: 'core-complex-selector--default',
+} satisfies ComponentDoc;