@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/Kbd/Kbd.test.tsx

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Kbd.test.tsx
+ * @input Uses React Testing Library, Kbd
+ * @output Tests for Kbd component
+ *
+ * Note: Tests run in jsdom which reports a non-Mac platform,
+ * so `mod` resolves to "Ctrl" rather than "\u2318" after the layout effect.
+ */
+
+import {render, screen} from '@testing-library/react';
+import {describe, it, expect, afterEach} from 'vitest';
+import {Kbd} from './Kbd';
+
+describe('Kbd', () => {
+  const originalPlatform = navigator.platform;
+
+  afterEach(() => {
+    // Restore platform after any test that spoofs it \u2014 ensures no
+    // test pollution even if an assertion fails mid-test.
+    Object.defineProperty(navigator, 'platform', {
+      value: originalPlatform,
+      configurable: true,
+    });
+  });
+
+  it('renders a single key', () => {
+    render(<Kbd keys="k" />);
+    const kbd = screen.getByText('K');
+    expect(kbd.tagName).toBe('KBD');
+  });
+
+  it('renders multiple keys separated by +', () => {
+    render(<Kbd keys="mod+k" />);
+    // In jsdom (non-Mac), mod renders as "Ctrl"
+    expect(screen.getByText('Ctrl')).toBeInTheDocument();
+    expect(screen.getByText('K')).toBeInTheDocument();
+  });
+
+  it('renders mod as Ctrl on non-Mac platforms', () => {
+    // jsdom is a non-Mac environment, so mod \u2192 Ctrl
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('Ctrl')).toBeInTheDocument();
+  });
+
+  it('renders mod as \u2318 on Mac platforms', () => {
+    Object.defineProperty(navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true,
+    });
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
+  });
+
+  it('maps modifier keys to symbols', () => {
+    render(<Kbd keys="ctrl+alt+shift+k" />);
+    expect(screen.getByText('\u2303')).toBeInTheDocument(); // \u2303
+    expect(screen.getByText('\u2325')).toBeInTheDocument(); // \u2325
+    expect(screen.getByText('\u21E7')).toBeInTheDocument(); // \u21E7
+    expect(screen.getByText('K')).toBeInTheDocument();
+  });
+
+  it('maps special keys', () => {
+    render(<Kbd keys="enter" />);
+    expect(screen.getByText('\u21B5')).toBeInTheDocument(); // \u21B5
+  });
+
+  it('renders escape as text', () => {
+    render(<Kbd keys="escape" />);
+    expect(screen.getByText('Esc')).toBeInTheDocument();
+  });
+
+  it('is aria-hidden', () => {
+    const {container} = render(<Kbd keys="mod+k" />);
+    const wrapper = container.firstChild as HTMLElement;
+    expect(wrapper.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('uppercases unknown keys', () => {
+    render(<Kbd keys="f1" />);
+    expect(screen.getByText('F1')).toBeInTheDocument();
+  });
+
+  it('handles whitespace around keys', () => {
+    render(<Kbd keys="mod + k" />);
+    // In jsdom (non-Mac), mod renders as "Ctrl"
+    expect(screen.getByText('Ctrl')).toBeInTheDocument();
+    expect(screen.getByText('K')).toBeInTheDocument();
+  });
+
+  it('renders astryx-* class names for theme targeting', () => {
+    const {container} = render(<Kbd keys="k" />);
+    const wrapper = container.firstChild as HTMLElement;
+    expect(wrapper.className).toContain('astryx-kbd');
+  });
+
+  it('renders "plus" as a literal + key', () => {
+    render(<Kbd keys="shift+plus" />);
+    expect(screen.getByText('⇧')).toBeInTheDocument();
+    expect(screen.getByText('+')).toBeInTheDocument();
+  });
+});

package/src/Kbd/Kbd.tsx

@@ -0,0 +1,185 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Kbd.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports Kbd component and KbdProps
+ * @position Core implementation; renders styled keyboard shortcut indicators
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Kbd/index.ts
+ * - /packages/cli/templates/blocks/components/Kbd/ (showcase blocks)
+ */
+
+import React, {useSyncExternalStore} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {themeProps} from '../utils/themeProps';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  typographyVars,
+  fontWeightVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+
+const styles = stylex.create({
+  wrapper: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    flexShrink: 0,
+  },
+  kbd: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minWidth: spacingVars['--spacing-5'],
+    height: spacingVars['--spacing-5'],
+    paddingInline: spacingVars['--spacing-1'],
+    borderRadius: radiusVars['--radius-inner'],
+    backgroundColor: colorVars['--color-neutral'],
+    borderBottomWidth: '2px',
+    borderBottomStyle: 'solid',
+    borderBottomColor: colorVars['--color-border'],
+    color: colorVars['--color-text-secondary'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    fontWeight: fontWeightVars['--font-weight-medium'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    userSelect: 'none',
+  },
+});
+
+/**
+ * Map of modifier key names to display symbols.
+ * Note: `mod` is not in this map — it resolves dynamically via platform
+ * detection inside the component.
+ */
+const KEY_DISPLAY: Record<string, string> = {
+  ctrl: '\u2303', // ⌃
+  alt: '\u2325', // ⌥
+  shift: '\u21E7', // ⇧
+  enter: '\u21B5', // ↵
+  backspace: '\u232B', // ⌫
+  escape: 'Esc',
+  tab: '\u21E5', // ⇥
+  up: '\u2191',
+  down: '\u2193',
+  left: '\u2190',
+  right: '\u2192',
+  plus: '+',
+};
+
+/**
+ * Resolves a key name to its display string. Handles the platform-aware
+ * `mod` key (⌘ on macOS, Ctrl on other platforms) and falls back to
+ * KEY_DISPLAY or uppercased key name.
+ */
+function getKeyDisplay(key: string, isMac: boolean): string {
+  if (key === 'mod') {
+    return isMac ? '\u2318' : 'Ctrl';
+  }
+  return KEY_DISPLAY[key] ?? key.toUpperCase();
+}
+
+function subscribeToPlatformChanges(): () => void {
+  return () => {};
+}
+
+function getServerPlatformSnapshot(): boolean {
+  return false;
+}
+
+/**
+ * Detects whether the current platform is macOS/iOS.
+ * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
+ * falls back to navigator.platform (deprecated but universally supported).
+ */
+function detectMac(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+  // Prefer User-Agent Client Hints API (not deprecated)
+  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
+  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
+    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+  }
+  // Fallback: navigator.platform (deprecated but still shipped everywhere)
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
+}
+
+export interface KbdProps extends BaseProps<HTMLSpanElement> {
+  ref?: React.Ref<HTMLSpanElement>;
+  /**
+   * Keyboard shortcut string. Use "+" to separate keys.
+   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
+   * Use "plus" to render a literal "+" key (e.g. "shift+plus").
+   *
+   * @example
+   * ```
+   * "mod+k"
+   * "mod+shift+p"
+   * "shift+plus"
+   * "enter"
+   * ```
+   */
+  keys: string;
+}
+
+/**
+ * Displays a keyboard shortcut as styled <kbd> elements.
+ *
+ * A general-purpose component for rendering keyboard shortcuts
+ * anywhere in the system — tooltips, menus, documentation, etc.
+ *
+ * Platform-aware: `mod` renders as ⌘ on macOS and Ctrl elsewhere.
+ * SSR-safe — defers platform detection through useSyncExternalStore to avoid
+ * hydration mismatches.
+ *
+ * @example
+ * ```
+ * <Kbd keys="mod+k" />
+ * ```
+ */
+export function Kbd({
+  keys,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: KbdProps) {
+  const isMac = useSyncExternalStore(
+    subscribeToPlatformChanges,
+    detectMac,
+    getServerPlatformSnapshot,
+  );
+
+  const parts = keys.split('+').map(key => key.trim().toLowerCase());
+
+  return (
+    <span
+      ref={ref}
+      {...rest}
+      {...mergeProps(
+        themeProps('kbd'),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}
+      aria-hidden="true">
+      {parts.map(key => (
+        <kbd key={key} {...stylex.props(styles.kbd)}>
+          {getKeyDisplay(key, isMac)}
+        </kbd>
+      ))}
+    </span>
+  );
+}
+
+Kbd.displayName = 'Kbd';

package/src/Kbd/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports Kbd component and types
+ * @output Exports public API for @astryxdesign/core Kbd
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+
+export {Kbd} from './Kbd';
+export type {KbdProps} from './Kbd';

package/src/Layer/Layer.doc.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docs = {
+  name: 'Layer',
+  displayName: 'Layer',
+  group: 'Utilities',
+  category: 'Utility',
+  keywords: [
+    'layer',
+    'overlay',
+    'popover',
+    'positioning',
+    'anchor',
+    'floating',
+    'dropdown',
+    'popper',
+    'popup',
+    'portal',
+  ],
+  usage: {
+    description:
+      'Layer utilities provide the app-level provider used by overlay systems. Use LayerProvider at the app root for toast/layer configuration; use higher-level Popover, HoverCard, or Tooltip APIs for most overlay UI.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use LayerProvider once near the app root when you need shared toast/layer configuration.',
+      },
+      {
+        guidance: true,
+        description:
+          'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add nested LayerProvider instances: nested providers are ignored and add unnecessary tree depth.',
+      },
+    ],
+  },
+  components: [
+    {
+      name: 'LayerProvider',
+      displayName: 'Layer Provider',
+      description:
+        'App-level provider for layer systems such as toast viewports and imperative modals. Nested providers pass through.',
+      props: [
+        {
+          name: 'children',
+          type: 'ReactNode',
+          description: 'Application subtree that can use the shared layer context.',
+          required: true,
+        },
+        {
+          name: 'toast',
+          type: 'LayerToastConfig',
+          description:
+            'Toast viewport configuration. Controls position, maxVisible, and inset for toasts shown through useToast.',
+        },
+      ],
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  usage: {
+    description:
+      'App-level provider for overlay systems. Use LayerProvider at app root for toast/layer config; use Popover/HoverCard/Tooltip for most overlay UI.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use LayerProvider once near app root for shared toast/layer config.',
+      },
+      {
+        guidance: true,
+        description: 'Use Popover/HoverCard/Tooltip for common overlay patterns.',
+      },
+      {
+        guidance: false,
+        description: 'Add nested LayerProvider instances.',
+      },
+    ],
+  },
+  components: [
+    {
+      name: 'LayerProvider',
+      description: 'App-level provider for toast/layer systems.',
+      propDescriptions: {
+        children: 'application subtree using shared layer context',
+        toast: 'toast viewport config: position, maxVisible, inset',
+      },
+    },
+  ],
+};

package/src/Layer/LayerContext.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file LayerContext.ts
+ * @input React context
+ * @output Exports LayerContext and related types
+ * @position Context definition for LayerProvider
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/LayerProvider.tsx
+ */
+
+import {createContext, use} from 'react';
+
+/**
+ * Toast configuration passed through the layer provider.
+ */
+export interface LayerToastConfig {
+  /** Position of the toast stack. @default 'bottomEnd' */
+  position?: 'topEnd' | 'topStart' | 'bottomEnd' | 'bottomStart';
+  /** Maximum visible toasts. @default 5 */
+  maxVisible?: number;
+  /** Inset from viewport edges. */
+  inset?: {
+    top?: number;
+    bottom?: number;
+    start?: number;
+    end?: number;
+  };
+}
+
+/**
+ * Context value provided by LayerProvider.
+ */
+export interface LayerContextValue {
+  /** Toast configuration from the provider. */
+  toastConfig: LayerToastConfig;
+  /** Whether this is a real provider (not fallback). */
+  isProvider: true;
+}
+
+/**
+ * React context for the layer provider.
+ * Default value is null — hooks detect this and use the fallback.
+ */
+export const LayerContext = createContext<LayerContextValue | null>(null);
+LayerContext.displayName = 'LayerContext';
+
+/**
+ * Hook to access the layer context. Returns null if no provider exists.
+ */
+export function useLayerContext(): LayerContextValue | null {
+  return use(LayerContext);
+}

package/src/Layer/LayerProvider.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo, type ReactNode} from 'react';
+import {
+  LayerContext,
+  useLayerContext,
+  type LayerContextValue,
+  type LayerToastConfig,
+} from './LayerContext';
+import {ToastViewport} from '../Toast/ToastViewport';
+
+export interface LayerProviderProps {
+  children: ReactNode;
+  /** Toast configuration. Omit to use defaults. */
+  toast?: LayerToastConfig;
+}
+
+/**
+ * App-level provider for layer systems (toast, sheet, imperative modals).
+ *
+ * Optional — hooks fall back to a lazy self-mounting viewport when no
+ * provider exists. Nested providers are no-ops.
+ *
+ * @example
+ * ```
+ * <LayerProvider toast={{ position: 'topEnd', maxVisible: 3 }}>
+ *   <App />
+ * </LayerProvider>
+ * ```
+ */
+const DEFAULT_TOAST_CONFIG = {};
+
+export function LayerProvider({
+  children,
+  toast: toastConfig = DEFAULT_TOAST_CONFIG,
+}: LayerProviderProps) {
+  const existingContext = useLayerContext();
+
+  const contextValue = useMemo<LayerContextValue>(
+    () => ({toastConfig, isProvider: true}),
+    [toastConfig],
+  );
+
+  // Nested provider — pass through
+  if (existingContext) {
+    return <>{children}</>;
+  }
+
+  return (
+    <LayerContext value={contextValue}>
+      <ToastViewport
+        position={toastConfig.position}
+        maxVisible={toastConfig.maxVisible}
+        inset={toastConfig.inset}>
+        {children}
+      </ToastViewport>
+    </LayerContext>
+  );
+}
+
+LayerProvider.displayName = 'LayerProvider';

package/src/Layer/index.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Layer hooks and components
+ * @output Exports all Layer module public API
+ * @position Entry point for Layer module
+ *
+ * SYNC: When adding new Layer files, update exports here
+ *
+ * NOTE: Popover, HoverCard, and Tooltip have been moved to their own
+ * top-level directories. They are re-exported here for backward compatibility.
+ * New code should import from @astryxdesign/core/Popover, @astryxdesign/core/HoverCard,
+ * or @astryxdesign/core/Tooltip directly.
+ */
+
+// Core layer hook (remains in Layer)
+export {useLayer} from './useLayer';
+export type {
+  LayerAlignment,
+  LayerPlacement,
+  ContextRenderProps,
+  FixedRenderProps,
+  ContextLayerOptions,
+  FixedLayerOptions,
+  ContextLayerReturn,
+  FixedLayerReturn,
+} from './useLayer';
+
+// Layer provider
+export {LayerProvider} from './LayerProvider';
+export type {LayerProviderProps} from './LayerProvider';
+export {LayerContext, useLayerContext} from './LayerContext';
+export type {LayerContextValue, LayerToastConfig} from './LayerContext';
+
+// Shared entry animation styles for layer-based components
+export {layerAnimations} from './layerAnimations.stylex';
+
+// Re-export Popover from new location (backward compat)
+export {usePopover, Popover} from '../Popover';
+export type {
+  UsePopoverOptions,
+  UsePopoverReturn,
+  PopoverProps,
+} from '../Popover';
+
+// Re-export HoverCard from new location (backward compat)
+export {useHoverCard, HoverCard} from '../HoverCard';
+export type {
+  HoverCardFocusTrigger,
+  HoverCardOptions,
+  HoverCardReturn,
+  HoverCardProps,
+} from '../HoverCard';
+
+// Re-export Tooltip from new location (backward compat)
+export {useTooltip, Tooltip} from '../Tooltip';
+export type {
+  TooltipFocusTrigger,
+  TooltipOptions,
+  TooltipReturn,
+  TooltipProps,
+} from '../Tooltip';

package/src/Layer/layerAnimations.stylex.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerAnimations.stylex.ts
+ * @input Uses StyleX, theme duration/easing tokens
+ * @output Exports shared entry animation styles for layer-based components
+ * @position Shared animation primitives; consumed by DropdownMenu, Popover,
+ *   HoverCard, Tooltip, Selector, and any component using useLayer
+ *
+ * Provides opt-in entry animations for popover/layer components.
+ * Components apply these via the `xstyle` prop on `layer.render()`.
+ *
+ * @example
+ * ```
+ * import {layerAnimations} from '../Layer/layerAnimations.stylex';
+ *
+ * // Direction-aware (for components that know placement):
+ * layer.render(<Content />, {
+ *   xstyle: layerAnimations[placement],
+ * });
+ *
+ * // Fixed direction:
+ * layer.render(<Content />, {
+ *   xstyle: layerAnimations.below,
+ * });
+ * ```
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
+
+const enterBelow = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateY(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateY(0) scale(1)'},
+});
+
+const enterAbove = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateY(${spacingVars['--spacing-2']}) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateY(0) scale(1)'},
+});
+
+const enterEnd = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
+const enterStart = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(${spacingVars['--spacing-2']}) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
+const animationBase = {
+  animationDuration: durationVars['--duration-fast-max'],
+  animationTimingFunction: easeVars['--ease-standard'],
+  animationFillMode: 'backwards' as const,
+};
+
+/**
+ * Shared entry animation styles for layer-based components.
+ *
+ * Keyed by LayerPlacement ('above' | 'below' | 'start' | 'end')
+ * for easy lookup: `layerAnimations[placement]`.
+ */
+export const layerAnimations = stylex.create({
+  below: {
+    animationName: enterBelow,
+    ...animationBase,
+  },
+  above: {
+    animationName: enterAbove,
+    ...animationBase,
+  },
+  end: {
+    animationName: enterEnd,
+    ...animationBase,
+  },
+  start: {
+    animationName: enterStart,
+    ...animationBase,
+  },
+});