@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Resizable/Resizable.tsx

@@ -0,0 +1,118 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {ResizeHandle} from '../ResizeHandle/index.js';
+
+const styles = stylex.create({
+  frame: {
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    minWidth: 0,
+  },
+  panel: {flexShrink: 0, minWidth: 0, overflow: 'auto'},
+  rest: {flexGrow: 1, minWidth: 0, overflow: 'auto'},
+});
+
+/** Props for a two-panel split whose divider can be moved. */
+export interface ResizableProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly handleLabel?: string;
+  readonly max?: number;
+  readonly min?: number;
+  readonly onSizeChange?: (size: number) => void;
+  readonly panel: ReactNode;
+  readonly size?: number;
+  readonly step?: number;
+}
+
+/**
+ * Splits a region into a sized panel and the rest. The divider is a real
+ * `separator` control, so arrow keys move it — a drag handle that only
+ * responds to a pointer is unusable by keyboard.
+ */
+export function Resizable({
+  children,
+  handleLabel,
+  max = 480,
+  min = 160,
+  onSizeChange,
+  panel,
+  size,
+  step = 16,
+  ...props
+}: ResizableProps) {
+  const frameRef = useRef<HTMLDivElement>(null);
+  const [internalSize, setInternalSize] = useState(size ?? 240);
+  const current = size ?? internalSize;
+  const [dragging, setDragging] = useState(false);
+
+  const apply = useCallback(
+    (next: number) => {
+      const clamped = Math.min(Math.max(next, min), max);
+      if (size === undefined) {
+        setInternalSize(clamped);
+      }
+      onSizeChange?.(clamped);
+    },
+    [max, min, onSizeChange, size],
+  );
+
+  useEffect(() => {
+    if (!dragging) {
+      return;
+    }
+
+    function handleMove(event: MouseEvent) {
+      const frame = frameRef.current;
+      if (frame) {
+        apply(event.clientX - frame.getBoundingClientRect().left);
+      }
+    }
+    function stop() {
+      setDragging(false);
+    }
+
+    document.addEventListener('mousemove', handleMove);
+    document.addEventListener('mouseup', stop);
+    return () => {
+      document.removeEventListener('mousemove', handleMove);
+      document.removeEventListener('mouseup', stop);
+    };
+  }, [apply, dragging]);
+
+  return (
+    <div {...props} ref={frameRef} {...stylex.props(styles.frame)}>
+      <div
+        {...stylex.props(styles.panel, scrolling.region)}
+        style={{width: `${current}px`}}
+      >
+        {panel}
+      </div>
+      <ResizeHandle
+        dragging={dragging}
+        label={handleLabel}
+        max={max}
+        min={min}
+        onMouseDown={() => {
+          setDragging(true);
+        }}
+        onValueChange={apply}
+        step={step}
+        value={current}
+      />
+      <div {...stylex.props(styles.rest, scrolling.region)}>{children}</div>
+    </div>
+  );
+}

package/src/Resizable/index.ts

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

package/src/ResizeHandle/ResizeHandle.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const resizeHandleDoc = {
+  name: 'ResizeHandle',
+  description: 'Divides two panes with a control arrow keys can move.',
+  props: [
+    {name: 'label', description: 'Names the divider control.'},
+    {name: 'max', description: 'Reports and caps the largest value.'},
+    {name: 'min', description: 'Reports and caps the smallest value.'},
+    {name: 'onValueChange', description: 'Receives the next clamped value.'},
+    {name: 'orientation', description: 'Sets the axis the divider runs along.'},
+    {name: 'step', description: 'Sets how far each arrow key moves it.'},
+    {name: 'value', description: 'Reports where the divider currently sits.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except aria-label, aria-orientation, aria-valuemax, aria-valuemin, aria-valuenow, children, className, onKeyDown, role, and tabIndex',
+  ],
+  example:
+    '<ResizeHandle max={480} min={160} onValueChange={setWidth} value={width} />',
+  storyId: 'core-resize-handle--default',
+} satisfies ComponentDoc;

package/src/ResizeHandle/ResizeHandle.tsx

@@ -0,0 +1,162 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, KeyboardEvent} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useInternationalization} from '../i18n/index.js';
+import {clamp} from '../utils/index.js';
+
+const styles = stylex.create({
+  // The divider is a hairline like every other seam in this system; the grab
+  // area is widened by a pseudo-element instead of the visible box, and it is
+  // widened to the hit target the rest of the system uses — `Slider` writes
+  // the same token for its thumb. At the 6px it used to be, the thing a reader
+  // has to catch was a seventh of the size of everything else they can press.
+  handle: {
+    backgroundColor: semanticTokens.borderDefault,
+    borderStyle: 'none',
+    borderWidth: 0,
+    flexShrink: 0,
+    padding: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled)': {
+      backgroundColor: semanticTokens.borderInteractive,
+    },
+  },
+  // A drag begins by pressing a one-pixel rule and immediately moving off it,
+  // so hover is the wrong thing to hang the highlight on: it goes out on the
+  // first pixel of every drag while the drag is still going. The caller owns
+  // the fact and hands it back.
+  dragging: {backgroundColor: semanticTokens.borderInteractive},
+  vertical: {
+    cursor: 'col-resize',
+    inlineSize: semanticTokens.borderWidth,
+    '::before': {
+      blockSize: '100%',
+      content: '',
+      inlineSize: semanticTokens.sizeHitTarget,
+      insetBlockStart: 0,
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translateX(-50%)',
+    },
+  },
+  horizontal: {
+    blockSize: semanticTokens.borderWidth,
+    cursor: 'row-resize',
+    '::before': {
+      blockSize: semanticTokens.sizeHitTarget,
+      content: '',
+      inlineSize: '100%',
+      insetBlockStart: '50%',
+      insetInlineStart: 0,
+      position: 'absolute',
+      transform: 'translateY(-50%)',
+    },
+  },
+});
+
+/** Axis the divider itself runs along, as `aria-orientation` reports it. */
+export type ResizeHandleOrientation = 'horizontal' | 'vertical';
+
+/** Props for the movable divider a caller places between two panes. */
+export interface ResizeHandleProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  | 'aria-label'
+  | 'aria-orientation'
+  | 'aria-valuemax'
+  | 'aria-valuemin'
+  | 'aria-valuenow'
+  | 'children'
+  | 'className'
+  | 'onKeyDown'
+  | 'role'
+  | 'tabIndex'
+> {
+  readonly label?: string;
+  readonly max?: number;
+  readonly min?: number;
+  readonly onValueChange?: (value: number) => void;
+  /** Held while the caller is dragging, so the mark survives the pointer. */
+  readonly dragging?: boolean;
+  readonly orientation?: ResizeHandleOrientation;
+  readonly step?: number;
+  readonly value?: number;
+}
+
+/**
+ * The divider between two panes the caller lays out itself. It is a real
+ * `separator` control, so arrow keys move it — a drag handle that only
+ * responds to a pointer is unusable by keyboard. The value attributes appear
+ * only when the caller supplies the numbers behind them, because a separator
+ * that reports a range it does not have is worse than one that reports none.
+ */
+export function ResizeHandle({
+  dragging = false,
+  label,
+  max,
+  min,
+  onValueChange,
+  orientation = 'vertical',
+  step = 16,
+  value,
+  ...props
+}: ResizeHandleProps) {
+  const {messages} = useInternationalization();
+  // An unset bound is no bound: a caller that leaves `min` or `max` out has a
+  // range this handle cannot know, so it stops holding the value inside one.
+  const lowerBound = min ?? Number.NEGATIVE_INFINITY;
+  const upperBound = max ?? Number.POSITIVE_INFINITY;
+  const decreaseKey = orientation === 'vertical' ? 'ArrowLeft' : 'ArrowUp';
+  const increaseKey = orientation === 'vertical' ? 'ArrowRight' : 'ArrowDown';
+
+  function requestedValue(key: string) {
+    if (key === decreaseKey) {
+      return value === undefined ? undefined : value - step;
+    }
+    if (key === increaseKey) {
+      return value === undefined ? undefined : value + step;
+    }
+    if (key === 'Home') {
+      return min;
+    }
+    return key === 'End' ? max : undefined;
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const next = requestedValue(event.key);
+    if (next === undefined) {
+      return;
+    }
+
+    event.preventDefault();
+    onValueChange?.(clamp(next, lowerBound, upperBound));
+  }
+
+  return (
+    <div
+      {...props}
+      aria-label={label ?? messages.resizeHandle}
+      aria-orientation={orientation}
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={value}
+      onKeyDown={handleKeyDown}
+      role="separator"
+      {...stylex.props(
+        styles.handle,
+        styles[orientation],
+        dragging && styles.dragging,
+      )}
+      tabIndex={0}
+    />
+  );
+}

package/src/ResizeHandle/index.ts

@@ -0,0 +1,5 @@
+export {
+  ResizeHandle,
+  type ResizeHandleOrientation,
+  type ResizeHandleProps,
+} from './ResizeHandle.js';

package/src/SegmentedControl/SegmentedControl.tsx

@@ -10,11 +10,20 @@ import {
 import {semanticTokens} from '../authoring.stylex.js';
 
 const styles = stylex.create({
+  // A groove cut into the paper: the well colour, closed by the control's own
+  // edge at the strong rank so the channel reads as sunk rather than as a
+  // paler card. The edge is a real border, not a ring — this is a control.
   root: {
     backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
     borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
     display: 'inline-flex',
-    gap: semanticTokens.spacingXs,
+    // The options are adjacent segments of one channel, so nothing separates
+    // them but the edge of the block that floats.
+    gap: 0,
     padding: semanticTokens.spacingXs,
   },
   option: {
@@ -22,13 +31,17 @@ const styles = stylex.create({
     borderRadius: semanticTokens.radiusInner,
     borderStyle: 'none',
     boxSizing: 'border-box',
-    color: semanticTokens.colorText,
+    cursor: 'pointer',
     fontFamily: semanticTokens.fontFamilyBody,
-    fontSize: semanticTokens.fontSizeMd,
-    minHeight: semanticTokens.sizeControlMd,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    minHeight: semanticTokens.sizeControlSm,
     paddingBlock: semanticTokens.spacingXs,
-    paddingInline: semanticTokens.spacingSm,
-    ':disabled': {color: semanticTokens.colorDisabledText},
+    paddingInline: semanticTokens.spacingMd,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, box-shadow, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':disabled': {color: semanticTokens.colorDisabledText, cursor: 'default'},
     ':focus-visible': {
       outlineColor: semanticTokens.colorFocus,
       outlineOffset: semanticTokens.focusOffset,
@@ -36,14 +49,30 @@ const styles = stylex.create({
       outlineWidth: semanticTokens.focusWidth,
     },
   },
+  // Three ranks of ink carry the choice. An option you could still take is
+  // available, not current, and saying so in secondary ink is what lets the
+  // raised block underneath the current one stay as quiet as it is.
   unselected: {
+    color: semanticTokens.colorTextSecondary,
     ':active:not(:disabled)': {
       backgroundColor: semanticTokens.colorOverlayActive,
+      color: semanticTokens.colorText,
     },
-    ':hover:not(:disabled)': {
+    ':hover:not(:disabled):not(:active)': {
       backgroundColor: semanticTokens.colorOverlayHover,
+      color: semanticTokens.colorText,
     },
   },
+  // The one documented exception to the no-fill rule, and the reason is the
+  // metaphor: this control is a groove cut in the paper, and the option in
+  // force is the block that has floated back up to the surface. A rail beside
+  // it would say "chosen"; the paper says "this is the one you are on".
+  //
+  // It was briefly a rail, because in dark skins the raised rank measured
+  // 1.03:1 against this groove — but that was the palette inverting, not the
+  // design failing: `surfaceRaised` sat BELOW `surfaceMuted` in all three dark
+  // skins, so the thing that floats was darker than the well it floats out of.
+  // The palette is fixed; the design is the one the canvas drew.
   selected: {
     backgroundColor: semanticTokens.colorSurfaceRaised,
     boxShadow: semanticTokens.elevationLow,

package/src/SelectableCard/SelectableCard.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const selectableCardDoc = {
+  name: 'SelectableCard',
+  description: 'A card surface that records a choice.',
+  props: [
+    {name: 'description', description: 'Adds detail under the label.'},
+    {name: 'label', description: 'Names the choice.'},
+    {name: 'multiple', description: 'Allows several cards to hold at once.'},
+  ],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except checked, children, className, defaultChecked, and type',
+  ],
+  example: '<SelectableCard label="Standard" name="plan" value="standard" />',
+  storyId: 'core-selectable-card--default',
+} satisfies ComponentDoc;

package/src/SelectableCard/SelectableCard.tsx

@@ -0,0 +1,252 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useState,
+  type ChangeEvent,
+  type InputHTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// Selection is a 2px accent bar pressed against the leading edge, never a
+// fill or a tinted card. `focusWidth` is this system's 2px, so the bar and
+// the focus ring stay the same weight when a theme changes it.
+const selectionMark = `inset ${semanticTokens.focusWidth} 0 0 0 ${semanticTokens.colorAccent}`;
+
+const styles = stylex.create({
+  label: {
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
+    borderRadius: semanticTokens.radiusContainer,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    color: semanticTokens.colorText,
+    cursor: 'pointer',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    padding: semanticTokens.spacingLg,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty:
+      'background-color, background-image, border-color, box-shadow, color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  // The wash is laid over the card's fill rather than replacing it: the
+  // overlay token is a few per cent of ink, so assigning it to
+  // `backgroundColor` drops the surface and shows the canvas through.
+  unselected: {
+    boxShadow: 'none',
+    ':hover:not(:disabled)': {
+      backgroundImage: `linear-gradient(${semanticTokens.colorOverlayHover}, ${semanticTokens.colorOverlayHover})`,
+      borderColor: semanticTokens.borderInteractive,
+    },
+  },
+  selected: {
+    boxShadow: selectionMark,
+  },
+  disabled: {
+    backgroundColor: semanticTokens.colorDisabledSurface,
+    borderColor: semanticTokens.borderDisabled,
+    boxShadow: 'none',
+    color: semanticTokens.colorDisabledText,
+    cursor: 'default',
+  },
+  // Drawn here, like `CheckboxInput` and `RadioList`. Left native this took
+  // the engine's white fill and grey edge, and it was a step smaller than the
+  // box `CheckboxInput` draws — two controls asking the same question in the
+  // same form at two different sizes.
+  control: {
+    appearance: 'none',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    blockSize: semanticTokens.spacingLg,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    display: 'inline-block',
+    flexShrink: 0,
+    inlineSize: semanticTokens.spacingLg,
+    marginBlockStart: semanticTokens.spacingXs,
+    position: 'relative',
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  // One of several is a round well with a filled centre; any number of several
+  // is a square well with a tick. Both marks are ink, never a fill behind the
+  // whole control.
+  controlSingle: {borderRadius: semanticTokens.radiusFull},
+  controlCheckedSingle: {
+    '::before': {
+      backgroundColor: semanticTokens.colorText,
+      blockSize: '50%',
+      borderRadius: semanticTokens.radiusFull,
+      content: '',
+      inlineSize: '50%',
+      insetBlockStart: '50%',
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translate(-50%, -50%)',
+    },
+  },
+  controlCheckedMultiple: {
+    '::before': {
+      blockSize: '58%',
+      borderBlockEndColor: semanticTokens.colorText,
+      borderBlockEndStyle: semanticTokens.borderStyle,
+      borderBlockEndWidth: `calc(2 * ${semanticTokens.borderWidth})`,
+      borderInlineEndColor: semanticTokens.colorText,
+      borderInlineEndStyle: semanticTokens.borderStyle,
+      borderInlineEndWidth: `calc(2 * ${semanticTokens.borderWidth})`,
+      content: '',
+      inlineSize: '30%',
+      insetBlockStart: '50%',
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translate(-50%, -58%) rotate(45deg)',
+    },
+  },
+  controlDisabled: {
+    backgroundColor: semanticTokens.colorDisabledSurface,
+    borderColor: semanticTokens.borderDisabled,
+    '::before': {
+      backgroundColor: semanticTokens.colorDisabledText,
+      borderBlockEndColor: semanticTokens.colorDisabledText,
+      borderInlineEndColor: semanticTokens.colorDisabledText,
+    },
+  },
+  content: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: semanticTokens.spacingXs,
+  },
+  // Three ranks inside one card: the title is what the card is, so it takes
+  // the first rank at rest and gains weight when chosen; the description is
+  // what supports it, so it stays at the second. Holding the title at the
+  // description's rank until selection flattens the card into one grey block.
+  title: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    fontWeight: semanticTokens.fontWeightRegular,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+  titleSelected: {fontWeight: semanticTokens.fontWeightMedium},
+  titleDisabled: {color: semanticTokens.colorDisabledText},
+  description: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+  descriptionDisabled: {color: semanticTokens.colorDisabledText},
+});
+
+type SharedSelectableCardProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'checked' | 'children' | 'className' | 'defaultChecked' | 'type'
+> & {
+  readonly description?: ReactNode;
+  readonly label: ReactNode;
+  readonly multiple?: boolean;
+};
+
+type ControlledSelectableCardProps = SharedSelectableCardProps & {
+  readonly checked: boolean;
+  readonly defaultChecked?: never;
+  readonly onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+};
+
+type UncontrolledSelectableCardProps = SharedSelectableCardProps & {
+  readonly checked?: never;
+  readonly defaultChecked?: boolean;
+};
+
+/** Props for a card that carries its own selection control. */
+export type SelectableCardProps =
+  ControlledSelectableCardProps | UncontrolledSelectableCardProps;
+
+/**
+ * A card that records a choice. The whole surface is the label, so a click
+ * anywhere on it selects, and `multiple` decides whether choices exclude each
+ * other. Selection is tracked in state rather than through a `:has()`
+ * selector, which the build's StyleX policy does not allow.
+ */
+export function SelectableCard({
+  checked,
+  defaultChecked = false,
+  description,
+  disabled = false,
+  label,
+  multiple = false,
+  onChange,
+  ...props
+}: SelectableCardProps) {
+  const [internalChecked, setInternalChecked] = useState(defaultChecked);
+  const isChecked = checked ?? internalChecked;
+  const isSelected = isChecked && !disabled;
+
+  function handleChange(event: ChangeEvent<HTMLInputElement>) {
+    if (checked === undefined) {
+      setInternalChecked(event.currentTarget.checked);
+    }
+    onChange?.(event);
+  }
+
+  return (
+    <label
+      {...stylex.props(
+        styles.label,
+        disabled
+          ? styles.disabled
+          : isSelected
+            ? styles.selected
+            : styles.unselected,
+      )}
+    >
+      <input
+        {...props}
+        checked={isChecked}
+        disabled={disabled}
+        onChange={handleChange}
+        {...stylex.props(
+          styles.control,
+          !multiple && styles.controlSingle,
+          isChecked &&
+            (multiple
+              ? styles.controlCheckedMultiple
+              : styles.controlCheckedSingle),
+          disabled && styles.controlDisabled,
+        )}
+        type={multiple ? 'checkbox' : 'radio'}
+      />
+      <span {...stylex.props(styles.content)}>
+        <span
+          {...stylex.props(
+            styles.title,
+            isSelected && styles.titleSelected,
+            disabled && styles.titleDisabled,
+          )}
+        >
+          {label}
+        </span>
+        {description === undefined ? null : (
+          <span
+            {...stylex.props(
+              styles.description,
+              disabled && styles.descriptionDisabled,
+            )}
+          >
+            {description}
+          </span>
+        )}
+      </span>
+    </label>
+  );
+}

package/src/SelectableCard/index.ts

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

package/src/Selector/Selector.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const selectorDoc = {
+  name: 'Selector',
+  description: 'Chooses one option from a closed list.',
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled value.'},
+    {name: 'onValueChange', description: 'Receives the newly chosen value.'},
+    {name: 'options', description: 'Supplies the options in reading order.'},
+    {
+      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:
+    '<Selector onValueChange={setOwner} options={owners} value={owner} />',
+  storyId: 'core-selector--default',
+} satisfies ComponentDoc;