@misoto22/kioku-ui 0.0.0 → 0.2.0

package/dist/docs/index.js

@@ -1,33 +1,123 @@
 import { alertDoc } from '../Alert/Alert.doc.js';
+import { alertDialogDoc } from '../AlertDialog/AlertDialog.doc.js';
+import { appShellDoc } from '../AppShell/AppShell.doc.js';
 import { asyncStateDoc } from '../AsyncState/AsyncState.doc.js';
 import { badgeDoc } from '../Badge/Badge.doc.js';
+import { bottomSheetDoc } from '../BottomSheet/BottomSheet.doc.js';
+import { bottomSheetSwitcherDoc } from '../BottomSheetSwitcher/BottomSheetSwitcher.doc.js';
+import { breadcrumbsDoc } from '../Breadcrumbs/Breadcrumbs.doc.js';
 import { buttonDoc } from '../Button/Button.doc.js';
 import { cardDoc } from '../Card/Card.doc.js';
 import { cardFooterDoc } from '../CardFooter/CardFooter.doc.js';
 import { cardHeaderDoc } from '../CardHeader/CardHeader.doc.js';
 import { centerDoc } from '../Center/Center.doc.js';
+import { codeDoc } from '../Code/Code.doc.js';
+import { contextMenuDoc } from '../ContextMenu/ContextMenu.doc.js';
+import { dialogDoc } from '../Dialog/Dialog.doc.js';
 import { dividerDoc } from '../Divider/Divider.doc.js';
+import { dropdownMenuDoc, dropdownMenuItemDoc } from '../DropdownMenu/DropdownMenu.doc.js';
 import { emptyStateDoc } from '../EmptyState/EmptyState.doc.js';
+import { eyebrowDoc } from '../Eyebrow/Eyebrow.doc.js';
 import { fieldDoc } from '../Field/Field.doc.js';
 import { gridDoc } from '../Grid/Grid.doc.js';
 import { headingDoc } from '../Heading/Heading.doc.js';
+import { hoverCardDoc } from '../HoverCard/HoverCard.doc.js';
+import { iconDoc } from '../Icon/Icon.doc.js';
 import { iconButtonDoc } from '../IconButton/IconButton.doc.js';
+import { itemDoc } from '../Item/Item.doc.js';
+import { kbdDoc } from '../Kbd/Kbd.doc.js';
+import { layerDoc } from '../Layer/Layer.doc.js';
+import { layoutDoc } from '../Layout/Layout.doc.js';
+import { listDoc, listItemDoc } from '../List/List.doc.js';
 import { metricGridDoc } from '../MetricGrid/MetricGrid.doc.js';
+import { mobileNavDoc } from '../MobileNav/MobileNav.doc.js';
+import { moreMenuDoc } from '../MoreMenu/MoreMenu.doc.js';
+import { navIconDoc } from '../NavIcon/NavIcon.doc.js';
+import { navItemDoc } from '../NavItem/NavItem.doc.js';
+import { navMenuDoc } from '../NavMenu/NavMenu.doc.js';
+import { outlineDoc } from '../Outline/Outline.doc.js';
+import { overlayDoc } from '../Overlay/Overlay.doc.js';
+import { popoverDoc } from '../Popover/Popover.doc.js';
+import { paginationDoc } from '../Pagination/Pagination.doc.js';
 import { sectionDoc } from '../Section/Section.doc.js';
 import { segmentedControlDoc } from '../SegmentedControl/SegmentedControl.doc.js';
+import { sideNavDoc, sideNavSectionDoc } from '../SideNav/SideNav.doc.js';
 import { skeletonDoc } from '../Skeleton/Skeleton.doc.js';
 import { spinnerDoc } from '../Spinner/Spinner.doc.js';
 import { stackDoc } from '../Stack/Stack.doc.js';
 import { statusDotDoc } from '../StatusDot/StatusDot.doc.js';
+import { tabListDoc } from '../TabList/TabList.doc.js';
 import { tableBodyDoc, tableCaptionDoc, tableCellDoc, tableDoc, tableHeadDoc, tableHeaderCellDoc, tableRowDoc } from '../Table/Table.doc.js';
 import { textAreaDoc } from '../TextArea/TextArea.doc.js';
 import { textDoc } from '../Text/Text.doc.js';
 import { textInputDoc } from '../TextInput/TextInput.doc.js';
+import { toastDoc, toastProviderDoc } from '../Toast/Toast.doc.js';
+import { toolbarDoc } from '../Toolbar/Toolbar.doc.js';
 import { toggleDoc } from '../Toggle/Toggle.doc.js';
+import { topNavDoc } from '../TopNav/TopNav.doc.js';
+import { tooltipDoc } from '../Tooltip/Tooltip.doc.js';
 import { visuallyHiddenDoc } from '../VisuallyHidden/VisuallyHidden.doc.js';
 import { linkDoc, linkProviderDoc } from '../navigation/LinkProvider.doc.js';
 import { themeProviderDoc } from '../theme/Theme.doc.js';
+import { calendarDoc } from '../Calendar/Calendar.doc.js';
+import { checkboxInputDoc } from '../CheckboxInput/CheckboxInput.doc.js';
+import { checkboxListDoc } from '../CheckboxList/CheckboxList.doc.js';
+import { complexSelectorDoc } from '../ComplexSelector/ComplexSelector.doc.js';
+import { dateInputDoc } from '../DateInput/DateInput.doc.js';
+import { datePickerDoc } from '../DatePicker/DatePicker.doc.js';
+import { dateRangeInputDoc } from '../DateRangeInput/DateRangeInput.doc.js';
+import { dateTimeInputDoc } from '../DateTimeInput/DateTimeInput.doc.js';
+import { fieldStatusDoc } from '../FieldStatus/FieldStatus.doc.js';
+import { fileInputDoc } from '../FileInput/FileInput.doc.js';
+import { formLayoutDoc } from '../FormLayout/FormLayout.doc.js';
+import { inputGroupDoc } from '../InputGroup/InputGroup.doc.js';
+import { multiSelectorDoc } from '../MultiSelector/MultiSelector.doc.js';
+import { numberInputDoc } from '../NumberInput/NumberInput.doc.js';
+import { numeralDoc } from '../Numeral/Numeral.doc.js';
+import { radioListDoc } from '../RadioList/RadioList.doc.js';
+import { selectorDoc } from '../Selector/Selector.doc.js';
+import { sliderDoc } from '../Slider/Slider.doc.js';
+import { switchDoc } from '../Switch/Switch.doc.js';
+import { timeInputDoc } from '../TimeInput/TimeInput.doc.js';
+import { typeaheadDoc } from '../Typeahead/Typeahead.doc.js';
+import { aspectRatioDoc } from '../AspectRatio/AspectRatio.doc.js';
+import { avatarDoc } from '../Avatar/Avatar.doc.js';
+import { avatarGroupDoc } from '../AvatarGroup/AvatarGroup.doc.js';
+import { bannerDoc } from '../Banner/Banner.doc.js';
+import { blockquoteDoc } from '../Blockquote/Blockquote.doc.js';
+import { carouselDoc } from '../Carousel/Carousel.doc.js';
+import { citationDoc } from '../Citation/Citation.doc.js';
+import { codeBlockDoc } from '../CodeBlock/CodeBlock.doc.js';
+import { indicatorDoc } from '../Indicator/Indicator.doc.js';
+import { lightboxDoc } from '../Lightbox/Lightbox.doc.js';
+import { markdownDoc } from '../Markdown/Markdown.doc.js';
+import { metadataListDoc } from '../MetadataList/MetadataList.doc.js';
+import { progressBarDoc } from '../ProgressBar/ProgressBar.doc.js';
+import { thumbnailDoc } from '../Thumbnail/Thumbnail.doc.js';
+import { timestampDoc } from '../Timestamp/Timestamp.doc.js';
+import { tokenDoc } from '../Token/Token.doc.js';
+import { tokenizerDoc } from '../Tokenizer/Tokenizer.doc.js';
+import { buttonGroupDoc } from '../ButtonGroup/ButtonGroup.doc.js';
+import { clickableCardDoc } from '../ClickableCard/ClickableCard.doc.js';
+import { collapsibleDoc } from '../Collapsible/Collapsible.doc.js';
+import { commandPaletteDoc } from '../CommandPalette/CommandPalette.doc.js';
+import { hStackDoc } from '../HStack/HStack.doc.js';
+import { overflowListDoc } from '../OverflowList/OverflowList.doc.js';
+import { powerSearchDoc } from '../PowerSearch/PowerSearch.doc.js';
+import { resizableDoc } from '../Resizable/Resizable.doc.js';
+import { resizeHandleDoc } from '../ResizeHandle/ResizeHandle.doc.js';
+import { selectableCardDoc } from '../SelectableCard/SelectableCard.doc.js';
+import { toggleButtonDoc } from '../ToggleButton/ToggleButton.doc.js';
+import { treeListDoc } from '../TreeList/TreeList.doc.js';
+import { vStackDoc } from '../VStack/VStack.doc.js';
+import { chatComposerDoc, chatLayoutDoc, chatMessageDoc, chatMessageListDoc, chatMessageMetadataDoc, chatSystemMessageDoc, chatToolCallsDoc } from '../Chat/Chat.doc.js';
+import { internationalizationProviderDoc } from '../i18n/Internationalization.doc.js';
+import { boxDoc } from '../Box/Box.doc.js';
+import { toggleButtonGroupDoc } from '../ToggleButtonGroup/ToggleButtonGroup.doc.js';
+import { typeaheadItemDoc } from '../TypeaheadItem/TypeaheadItem.doc.js';
+import { topNavMenuDoc } from '../TopNavMenu/TopNavMenu.doc.js';
+import { topNavMegaMenuDoc, topNavMegaMenuFeaturedCardDoc } from '../TopNavMegaMenu/TopNavMegaMenu.doc.js';
 import "../styles/stylex.css";
-export { cardDoc, cardFooterDoc, cardHeaderDoc, centerDoc, dividerDoc, gridDoc, headingDoc, sectionDoc, stackDoc, textDoc, visuallyHiddenDoc, alertDoc, asyncStateDoc, badgeDoc, buttonDoc, emptyStateDoc, fieldDoc, iconButtonDoc, metricGridDoc, segmentedControlDoc, skeletonDoc, spinnerDoc, statusDotDoc, tableDoc, tableCaptionDoc, tableHeadDoc, tableBodyDoc, tableRowDoc, tableHeaderCellDoc, tableCellDoc, textAreaDoc, textInputDoc, toggleDoc, linkDoc, linkProviderDoc, themeProviderDoc };
+export { cardDoc, cardFooterDoc, cardHeaderDoc, centerDoc, codeDoc, contextMenuDoc, dialogDoc, dividerDoc, dropdownMenuDoc, dropdownMenuItemDoc, gridDoc, headingDoc, hoverCardDoc, sectionDoc, stackDoc, textDoc, visuallyHiddenDoc, alertDoc, alertDialogDoc, appShellDoc, asyncStateDoc, badgeDoc, bottomSheetDoc, bottomSheetSwitcherDoc, breadcrumbsDoc, buttonDoc, emptyStateDoc, eyebrowDoc, fieldDoc, iconDoc, iconButtonDoc, itemDoc, kbdDoc, layerDoc, layoutDoc, listDoc, listItemDoc, metricGridDoc, mobileNavDoc, moreMenuDoc, navIconDoc, navItemDoc, navMenuDoc, outlineDoc, overlayDoc, paginationDoc, popoverDoc, segmentedControlDoc, sideNavDoc, sideNavSectionDoc, skeletonDoc, spinnerDoc, statusDotDoc, tabListDoc, tableDoc, tableCaptionDoc, tableHeadDoc, tableBodyDoc, tableRowDoc, tableHeaderCellDoc, tableCellDoc, textAreaDoc, textInputDoc, toastDoc, toastProviderDoc, toggleDoc, toolbarDoc, tooltipDoc, topNavDoc, linkDoc, linkProviderDoc, calendarDoc, checkboxInputDoc, checkboxListDoc, complexSelectorDoc, dateInputDoc, datePickerDoc, dateRangeInputDoc, dateTimeInputDoc, fieldStatusDoc, fileInputDoc, formLayoutDoc, inputGroupDoc, multiSelectorDoc, numberInputDoc, numeralDoc, radioListDoc, selectorDoc, sliderDoc, switchDoc, timeInputDoc, typeaheadDoc, aspectRatioDoc, avatarDoc, avatarGroupDoc, bannerDoc, blockquoteDoc, carouselDoc, citationDoc, codeBlockDoc, indicatorDoc, lightboxDoc, markdownDoc, metadataListDoc, progressBarDoc, thumbnailDoc, timestampDoc, tokenDoc, tokenizerDoc, buttonGroupDoc, clickableCardDoc, collapsibleDoc, commandPaletteDoc, hStackDoc, overflowListDoc, powerSearchDoc, resizableDoc, resizeHandleDoc, selectableCardDoc, toggleButtonDoc, treeListDoc, vStackDoc, chatComposerDoc, chatLayoutDoc, chatMessageDoc, chatMessageListDoc, chatToolCallsDoc, internationalizationProviderDoc, boxDoc, toggleButtonGroupDoc, typeaheadItemDoc, topNavMenuDoc, chatMessageMetadataDoc, chatSystemMessageDoc, topNavMegaMenuDoc, topNavMegaMenuFeaturedCardDoc, themeProviderDoc };
 export { validateComponentDoc } from './types.js';
-export const componentDocs = Object.freeze([textDoc, headingDoc, stackDoc, gridDoc, sectionDoc, cardDoc, cardHeaderDoc, cardFooterDoc, dividerDoc, centerDoc, visuallyHiddenDoc, buttonDoc, iconButtonDoc, badgeDoc, statusDotDoc, fieldDoc, textInputDoc, textAreaDoc, toggleDoc, segmentedControlDoc, emptyStateDoc, asyncStateDoc, spinnerDoc, skeletonDoc, alertDoc, tableDoc, tableCaptionDoc, tableHeadDoc, tableBodyDoc, tableRowDoc, tableHeaderCellDoc, tableCellDoc, metricGridDoc, linkDoc, linkProviderDoc, themeProviderDoc]);
+export const componentDocs = Object.freeze([textDoc, headingDoc, codeDoc, kbdDoc, eyebrowDoc, numeralDoc, iconDoc, stackDoc, gridDoc, sectionDoc, cardDoc, cardHeaderDoc, cardFooterDoc, dividerDoc, centerDoc, listDoc, listItemDoc, itemDoc, visuallyHiddenDoc, buttonDoc, iconButtonDoc, badgeDoc, statusDotDoc, fieldDoc, textInputDoc, textAreaDoc, toggleDoc, segmentedControlDoc, checkboxInputDoc, checkboxListDoc, radioListDoc, switchDoc, selectorDoc, complexSelectorDoc, typeaheadDoc, typeaheadItemDoc, multiSelectorDoc, numberInputDoc, fileInputDoc, sliderDoc, dateInputDoc, datePickerDoc, timeInputDoc, dateTimeInputDoc, dateRangeInputDoc, calendarDoc, fieldStatusDoc, inputGroupDoc, formLayoutDoc, emptyStateDoc, asyncStateDoc, spinnerDoc, skeletonDoc, alertDoc, avatarDoc, avatarGroupDoc, thumbnailDoc, aspectRatioDoc, boxDoc, bannerDoc, blockquoteDoc, citationDoc, codeBlockDoc, markdownDoc, metadataListDoc, timestampDoc, tokenDoc, tokenizerDoc, progressBarDoc, indicatorDoc, carouselDoc, lightboxDoc, layerDoc, overlayDoc, popoverDoc, tooltipDoc, dialogDoc, alertDialogDoc, bottomSheetDoc, bottomSheetSwitcherDoc, hoverCardDoc, dropdownMenuDoc, dropdownMenuItemDoc, contextMenuDoc, moreMenuDoc, toastDoc, toastProviderDoc, tableDoc, tableCaptionDoc, tableHeadDoc, tableBodyDoc, tableRowDoc, tableHeaderCellDoc, tableCellDoc, metricGridDoc, hStackDoc, vStackDoc, buttonGroupDoc, toggleButtonDoc, toggleButtonGroupDoc, clickableCardDoc, selectableCardDoc, collapsibleDoc, resizableDoc, resizeHandleDoc, overflowListDoc, treeListDoc, commandPaletteDoc, powerSearchDoc, chatLayoutDoc, chatMessageListDoc, chatMessageDoc, chatMessageMetadataDoc, chatSystemMessageDoc, chatToolCallsDoc, chatComposerDoc, tabListDoc, breadcrumbsDoc, paginationDoc, navIconDoc, navItemDoc, navMenuDoc, topNavDoc, topNavMenuDoc, topNavMegaMenuDoc, topNavMegaMenuFeaturedCardDoc, sideNavDoc, sideNavSectionDoc, mobileNavDoc, toolbarDoc, outlineDoc, layoutDoc, appShellDoc, linkDoc, linkProviderDoc, internationalizationProviderDoc, themeProviderDoc]);

package/dist/hooks/focusableSelector.d.ts

@@ -0,0 +1,19 @@
+/** Matches elements the browser will place in the sequential focus order. */
+export declare const focusableSelector: string;
+/**
+ * Matches elements focus can reach programmatically, including the ones a
+ * roving-tabindex collection has deliberately taken out of the tab order.
+ */
+export declare const reachableSelector: string;
+/**
+ * Lists the focusable descendants of `root` in document order, skipping the
+ * ones a reader cannot reach because they are hidden, inert, or held out of
+ * the tab order by a negative tabIndex.
+ */
+export declare function focusableElements(root: HTMLElement): HTMLElement[];
+/**
+ * Lists the descendants a roving-focus collection can move between. Unlike
+ * `focusableElements` this keeps `tabindex="-1"` items, because that is how
+ * such a collection marks the stops it owns rather than the ones it hides.
+ */
+export declare function reachableElements(root: HTMLElement): HTMLElement[];

package/dist/hooks/focusableSelector.js

@@ -0,0 +1,42 @@
+import "../styles/stylex.css";
+const controlSelectors = ['a[href]', 'audio[controls]', 'button:not([disabled])', 'input:not([disabled]):not([type="hidden"])', 'select:not([disabled])', 'textarea:not([disabled])', 'video[controls]', '[contenteditable]:not([contenteditable="false"])'];
+
+/** Matches elements the browser will place in the sequential focus order. */
+export const focusableSelector = [...controlSelectors, '[tabindex]:not([tabindex="-1"])'].join(',');
+
+/**
+ * Matches elements focus can reach programmatically, including the ones a
+ * roving-tabindex collection has deliberately taken out of the tab order.
+ */
+export const reachableSelector = [...controlSelectors, '[tabindex]'].join(',');
+function isHidden(element) {
+  if (element.hidden) {
+    return true;
+  }
+
+  // Layout boxes are unreliable outside a real browser, so read the declared
+  // visibility instead of measuring the element.
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  return style?.display === 'none' || style?.visibility === 'hidden';
+}
+function collect(root, selector, requireTabOrder) {
+  return [...root.querySelectorAll(selector)].filter(element => (!requireTabOrder || element.tabIndex >= 0) && !element.hasAttribute('inert') && element.getAttribute('aria-hidden') !== 'true' && !isHidden(element));
+}
+
+/**
+ * Lists the focusable descendants of `root` in document order, skipping the
+ * ones a reader cannot reach because they are hidden, inert, or held out of
+ * the tab order by a negative tabIndex.
+ */
+export function focusableElements(root) {
+  return collect(root, focusableSelector, true);
+}
+
+/**
+ * Lists the descendants a roving-focus collection can move between. Unlike
+ * `focusableElements` this keeps `tabindex="-1"` items, because that is how
+ * such a collection marks the stops it owns rather than the ones it hides.
+ */
+export function reachableElements(root) {
+  return collect(root, reachableSelector, false);
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,11 @@
+export { focusableElements, focusableSelector, reachableElements, reachableSelector, } from './focusableSelector.js';
+export { useAnchoredPosition, type Alignment, type AnchoredPosition, type AnchoredPositionOptions, type AnchoredPositionResult, type Placement, } from './useAnchoredPosition.js';
+export { useAnnounce, type AnnouncePoliteness } from './useAnnounce.js';
+export { useClipboard, type ClipboardState } from './useClipboard.js';
+export { useDevWarning } from './useDevWarning.js';
+export { useFocusTrap } from './useFocusTrap.js';
+export { useHotkeys, type HotkeyBindings, type HotkeyOptions, } from './useHotkeys.js';
+export { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
+export { useListFocus, type ListFocusOptions, type ListOrientation, } from './useListFocus.js';
+export { useMediaQuery } from './useMediaQuery.js';
+export { useScrollLock } from './useScrollLock.js';

package/dist/hooks/index.js

@@ -0,0 +1,12 @@
+import "../styles/stylex.css";
+export { focusableElements, focusableSelector, reachableElements, reachableSelector } from './focusableSelector.js';
+export { useAnchoredPosition } from './useAnchoredPosition.js';
+export { useAnnounce } from './useAnnounce.js';
+export { useClipboard } from './useClipboard.js';
+export { useDevWarning } from './useDevWarning.js';
+export { useFocusTrap } from './useFocusTrap.js';
+export { useHotkeys } from './useHotkeys.js';
+export { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
+export { useListFocus } from './useListFocus.js';
+export { useMediaQuery } from './useMediaQuery.js';
+export { useScrollLock } from './useScrollLock.js';

package/dist/hooks/useAnchoredPosition.d.ts

@@ -0,0 +1,33 @@
+import { type RefObject } from 'react';
+/** Side of the anchor a floating surface prefers to occupy. */
+export type Placement = 'bottom' | 'left' | 'right' | 'top';
+/** How a floating surface lines up along the anchor's cross axis. */
+export type Alignment = 'center' | 'end' | 'start';
+/** Options controlling where a floating surface settles. */
+export interface AnchoredPositionOptions {
+    readonly alignment?: Alignment;
+    readonly offset?: number;
+    readonly placement?: Placement;
+}
+/** Resolved viewport coordinates for a floating surface. */
+export interface AnchoredPosition {
+    readonly left: number;
+    readonly placement: Placement;
+    readonly top: number;
+}
+/** The measured position plus the ref that feeds it. */
+export interface AnchoredPositionResult {
+    readonly position: AnchoredPosition | undefined;
+    readonly surface: HTMLElement | null;
+    readonly surfaceRef: (node: HTMLElement | null) => void;
+}
+/**
+ * Positions a floating surface against an anchor, flipping to the opposite
+ * side when the preferred one would leave the viewport and clamping whatever
+ * survives back inside it. Recomputed on scroll and resize while open.
+ *
+ * The surface is tracked through a callback ref rather than a plain ref
+ * because portalled surfaces mount after the caller renders; a ref would
+ * still read `null` when the first measurement runs.
+ */
+export declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, open: boolean, { alignment, offset, placement, }?: AnchoredPositionOptions): AnchoredPositionResult;

package/dist/hooks/useAnchoredPosition.js

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
+
+/** Side of the anchor a floating surface prefers to occupy. */
+import "../styles/stylex.css";
+/** How a floating surface lines up along the anchor's cross axis. */
+/** Options controlling where a floating surface settles. */
+/** Resolved viewport coordinates for a floating surface. */
+/** The measured position plus the ref that feeds it. */
+const opposite = {
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+  top: 'bottom'
+};
+function alignAcross(anchorStart, anchorSize, surfaceSize, alignment) {
+  if (alignment === 'center') {
+    return anchorStart + (anchorSize - surfaceSize) / 2;
+  }
+  return alignment === 'start' ? anchorStart : anchorStart + anchorSize - surfaceSize;
+}
+function place(anchor, surface, placement, alignment, offset) {
+  switch (placement) {
+    case 'top':
+      return {
+        left: alignAcross(anchor.left, anchor.width, surface.width, alignment),
+        top: anchor.top - surface.height - offset
+      };
+    case 'bottom':
+      return {
+        left: alignAcross(anchor.left, anchor.width, surface.width, alignment),
+        top: anchor.bottom + offset
+      };
+    case 'left':
+      return {
+        left: anchor.left - surface.width - offset,
+        top: alignAcross(anchor.top, anchor.height, surface.height, alignment)
+      };
+    case 'right':
+      return {
+        left: anchor.right + offset,
+        top: alignAcross(anchor.top, anchor.height, surface.height, alignment)
+      };
+  }
+}
+function fitsInViewport({
+  left,
+  top
+}, surface) {
+  return left >= 0 && top >= 0 && left + surface.width <= window.innerWidth && top + surface.height <= window.innerHeight;
+}
+function clampToViewport({
+  left,
+  top
+}, surface) {
+  return {
+    left: Math.max(0, Math.min(left, window.innerWidth - surface.width)),
+    top: Math.max(0, Math.min(top, window.innerHeight - surface.height))
+  };
+}
+
+/**
+ * Positions a floating surface against an anchor, flipping to the opposite
+ * side when the preferred one would leave the viewport and clamping whatever
+ * survives back inside it. Recomputed on scroll and resize while open.
+ *
+ * The surface is tracked through a callback ref rather than a plain ref
+ * because portalled surfaces mount after the caller renders; a ref would
+ * still read `null` when the first measurement runs.
+ */
+export function useAnchoredPosition(anchorRef, open, {
+  alignment = 'center',
+  offset = 8,
+  placement = 'bottom'
+} = {}) {
+  const [position, setPosition] = useState(undefined);
+  const [surfaceElement, setSurfaceElement] = useState(null);
+  const measure = useCallback(() => {
+    const anchorElement = anchorRef.current;
+    if (!anchorElement || !surfaceElement) {
+      return;
+    }
+    const anchor = anchorElement.getBoundingClientRect();
+    const surface = surfaceElement.getBoundingClientRect();
+    const preferred = place(anchor, surface, placement, alignment, offset);
+    const resolved = fitsInViewport(preferred, surface) ? {
+      ...preferred,
+      placement
+    } : {
+      ...place(anchor, surface, opposite[placement], alignment, offset),
+      placement: opposite[placement]
+    };
+    setPosition({
+      ...clampToViewport(resolved, surface),
+      placement: resolved.placement
+    });
+  }, [alignment, anchorRef, offset, placement, surfaceElement]);
+  useIsomorphicLayoutEffect(() => {
+    if (open) {
+      measure();
+    } else {
+      setPosition(undefined);
+    }
+  }, [measure, open]);
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    window.addEventListener('resize', measure);
+    window.addEventListener('scroll', measure, true);
+    return () => {
+      window.removeEventListener('resize', measure);
+      window.removeEventListener('scroll', measure, true);
+    };
+  }, [measure, open]);
+  return {
+    position,
+    surface: surfaceElement,
+    surfaceRef: setSurfaceElement
+  };
+}

package/dist/hooks/useAnnounce.d.ts

@@ -0,0 +1,7 @@
+/** Urgency levels a live-region announcement can claim. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * Returns a function that speaks a message through an owned live region.
+ * The region is created lazily and removed with the component that owns it.
+ */
+export declare function useAnnounce(): (message: string, politeness?: AnnouncePoliteness) => void;

package/dist/hooks/useAnnounce.js

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+/** Urgency levels a live-region announcement can claim. */
+import "../styles/stylex.css";
+const regionStyle = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0';
+
+/**
+ * Returns a function that speaks a message through an owned live region.
+ * The region is created lazily and removed with the component that owns it.
+ */
+export function useAnnounce() {
+  const regionRef = useRef(null);
+  useEffect(() => () => {
+    regionRef.current?.remove();
+    regionRef.current = null;
+  }, []);
+  return useCallback((message, politeness = 'polite') => {
+    if (typeof document === 'undefined' || message.trim() === '') {
+      return;
+    }
+    let region = regionRef.current;
+    if (!region) {
+      region = document.createElement('div');
+      region.setAttribute('role', 'status');
+      region.setAttribute('style', regionStyle);
+      document.body.append(region);
+      regionRef.current = region;
+    }
+    region.setAttribute('aria-live', politeness);
+    // Clearing first forces assistive technology to re-read an identical message.
+    region.textContent = '';
+    region.textContent = message;
+  }, []);
+}

package/dist/hooks/useClipboard.d.ts

@@ -0,0 +1,10 @@
+/** Result of a clipboard hook: the copy action and its recent outcome. */
+export interface ClipboardState {
+    readonly copied: boolean;
+    readonly copy: (text: string) => Promise<boolean>;
+}
+/**
+ * Copies text and reports success for `resetAfterMs`, so a caller can show a
+ * confirmation without owning its own timer.
+ */
+export declare function useClipboard(resetAfterMs?: number): ClipboardState;

package/dist/hooks/useClipboard.js

@@ -0,0 +1,36 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** Result of a clipboard hook: the copy action and its recent outcome. */
+import "../styles/stylex.css";
+/**
+ * Copies text and reports success for `resetAfterMs`, so a caller can show a
+ * confirmation without owning its own timer.
+ */
+export function useClipboard(resetAfterMs = 2000) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef(undefined);
+  useEffect(() => () => {
+    clearTimeout(timer.current);
+  }, []);
+  const copy = useCallback(async text => {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) {
+      return false;
+    }
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      setCopied(false);
+      return false;
+    }
+    setCopied(true);
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      setCopied(false);
+    }, resetAfterMs);
+    return true;
+  }, [resetAfterMs]);
+  return {
+    copied,
+    copy
+  };
+}

package/dist/hooks/useDevWarning.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reports a broken component contract once per mount during development.
+ * Production builds stay silent so hosts never pay for the check.
+ */
+export declare function useDevWarning(condition: boolean, message: string): void;

package/dist/hooks/useDevWarning.js

@@ -0,0 +1,20 @@
+import { useEffect, useRef } from 'react';
+import "../styles/stylex.css";
+function isProduction() {
+  return typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production';
+}
+
+/**
+ * Reports a broken component contract once per mount during development.
+ * Production builds stay silent so hosts never pay for the check.
+ */
+export function useDevWarning(condition, message) {
+  const warned = useRef(false);
+  useEffect(() => {
+    if (isProduction() || !condition || warned.current) {
+      return;
+    }
+    warned.current = true;
+    console.warn(message);
+  }, [condition, message]);
+}

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Confines Tab and Shift+Tab to the descendants of `container` while `active`
+ * is true, then returns focus to whatever held it before the trap opened.
+ *
+ * The container is passed as an element rather than a ref because portalled
+ * surfaces mount after their owner renders; a ref would still read `null`
+ * when this effect first runs, and the trap would never arm.
+ */
+export declare function useFocusTrap(container: HTMLElement | null, active: boolean): void;

package/dist/hooks/useFocusTrap.js

@@ -0,0 +1,57 @@
+import { useEffect } from 'react';
+import { focusableElements } from './focusableSelector.js';
+
+/**
+ * Confines Tab and Shift+Tab to the descendants of `container` while `active`
+ * is true, then returns focus to whatever held it before the trap opened.
+ *
+ * The container is passed as an element rather than a ref because portalled
+ * surfaces mount after their owner renders; a ref would still read `null`
+ * when this effect first runs, and the trap would never arm.
+ */
+import "../styles/stylex.css";
+export function useFocusTrap(container, active) {
+  useEffect(() => {
+    if (!active || !container) {
+      return;
+    }
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const [initial] = focusableElements(container);
+    (initial ?? container).focus({
+      preventScroll: true
+    });
+    function handleKeyDown(event) {
+      if (event.key !== 'Tab' || !container) {
+        return;
+      }
+      const focusable = focusableElements(container);
+      if (focusable.length === 0) {
+        event.preventDefault();
+        return;
+      }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      const target = document.activeElement;
+      if (event.shiftKey && (target === first || !container.contains(target))) {
+        event.preventDefault();
+        last?.focus({
+          preventScroll: true
+        });
+        return;
+      }
+      if (!event.shiftKey && target === last) {
+        event.preventDefault();
+        first?.focus({
+          preventScroll: true
+        });
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown, true);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown, true);
+      previous?.focus({
+        preventScroll: true
+      });
+    };
+  }, [active, container]);
+}

package/dist/hooks/useHotkeys.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Maps a normalized shortcut to its handler. Combinations use `+` and the
+ * `mod` alias, which resolves to Command on Apple platforms and Control
+ * everywhere else: `mod+k`, `shift+?`, `Escape`.
+ */
+export type HotkeyBindings = Readonly<Record<string, (event: KeyboardEvent) => void>>;
+/** Options controlling when a hotkey map listens. */
+export interface HotkeyOptions {
+    readonly enabled?: boolean;
+}
+/** Runs a handler when its shortcut fires anywhere in the document. */
+export declare function useHotkeys(bindings: HotkeyBindings, { enabled }?: HotkeyOptions): void;

package/dist/hooks/useHotkeys.js

@@ -0,0 +1,57 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Maps a normalized shortcut to its handler. Combinations use `+` and the
+ * `mod` alias, which resolves to Command on Apple platforms and Control
+ * everywhere else: `mod+k`, `shift+?`, `Escape`.
+ */
+import "../styles/stylex.css";
+/** Options controlling when a hotkey map listens. */
+function isApplePlatform() {
+  return typeof navigator !== 'undefined' && /Mac|iPhone|iPad/u.test(navigator.platform);
+}
+function describe(event) {
+  const parts = [];
+  const mod = isApplePlatform() ? event.metaKey : event.ctrlKey;
+  if (mod) parts.push('mod');
+  if (event.altKey) parts.push('alt');
+  if (event.shiftKey) parts.push('shift');
+  parts.push(event.key.toLowerCase());
+  return parts.join('+');
+}
+const modifierOrder = ['mod', 'alt', 'shift'];
+
+// Non-modifiers rank last so `mod+k` and `K+MOD` describe the same shortcut.
+function rank(part) {
+  const index = modifierOrder.indexOf(part);
+  return index === -1 ? modifierOrder.length : index;
+}
+function normalize(binding) {
+  return binding.split('+').map(part => part.trim().toLowerCase()).sort((left, right) => rank(left) - rank(right)).join('+');
+}
+
+/** Runs a handler when its shortcut fires anywhere in the document. */
+export function useHotkeys(bindings, {
+  enabled = true
+} = {}) {
+  const bindingsRef = useRef(bindings);
+  bindingsRef.current = bindings;
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    function handleKeyDown(event) {
+      const pressed = describe(event);
+      for (const [binding, handler] of Object.entries(bindingsRef.current)) {
+        if (normalize(binding) === pressed) {
+          handler(event);
+          return;
+        }
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [enabled]);
+}

package/dist/hooks/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,6 @@
+import { useEffect } from 'react';
+/**
+ * Runs layout work before paint in the browser and falls back to a plain
+ * effect on the server, where React cannot run layout effects at all.
+ */
+export declare const useIsomorphicLayoutEffect: typeof useEffect;