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

package/src/AppShell/AppShellMobileContext.tsx

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AppShellMobileContext.tsx
+ * @input Uses React createContext, use
+ * @output Exports AppShellMobileContext, useAppShellMobile
+ * @position Internal context for mobile nav state; consumed by MobileNavToggle, TopNav (future)
+ *
+ * Provides mobile navigation state to any component in the AppShell tree.
+ * Used by MobileNavToggle to open/close the drawer and by TopNav (future)
+ * to adapt rendering based on mobile context.
+ */
+
+import {createContext, use} from 'react';
+
+export interface AppShellMobileContextValue {
+  /** Whether the viewport is below the mobile breakpoint */
+  isMobile: boolean;
+  /** Whether the mobile nav drawer is currently open */
+  isMobileNavOpen: boolean;
+  /** Toggle the mobile nav drawer open/closed */
+  toggleMobileNav: () => void;
+  /** Open the mobile nav drawer */
+  openMobileNav: () => void;
+  /** Close the mobile nav drawer */
+  closeMobileNav: () => void;
+  /** Whether mobile nav is enabled at all */
+  isMobileNavEnabled: boolean;
+  /** Whether auto-placed toggles should render (false in customToggle mode) */
+  hasAutoToggle: boolean;
+}
+
+const defaultValue: AppShellMobileContextValue = {
+  isMobile: false,
+  isMobileNavOpen: false,
+  toggleMobileNav: () => {},
+  openMobileNav: () => {},
+  closeMobileNav: () => {},
+  isMobileNavEnabled: false,
+  hasAutoToggle: true,
+};
+
+export const AppShellMobileContext =
+  createContext<AppShellMobileContextValue>(defaultValue);
+AppShellMobileContext.displayName = 'AppShellMobileContext';
+
+/**
+ * Hook to access mobile nav state from anywhere in the AppShell tree.
+ */
+export function useAppShellMobile(): AppShellMobileContextValue {
+  return use(AppShellMobileContext);
+}

package/src/AppShell/index.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports AppShell component and types from AppShell.tsx
+ * @output Exports AppShell and related types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs
+ */
+
+export {AppShell} from './AppShell';
+export type {
+  AppShellProps,
+  AppShellBreakpoint,
+  AppShellVariant,
+  AppShellVariantMap,
+  MobileNavConfig,
+} from './AppShell';
+export {
+  useAppShellMobile,
+  AppShellMobileContext,
+} from './AppShellMobileContext';
+export type {AppShellMobileContextValue} from './AppShellMobileContext';

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useAppShellMobile',
+  displayName: 'useAppShellMobile',
+  group: 'AppShell',
+  category: 'layout',
+  keywords: [
+    'appshell',
+    'mobile nav',
+    'mobile drawer',
+    'hamburger',
+    'navigation toggle',
+    'responsive navigation',
+    'drawer state',
+  ],
+  params: [
+    // useAppShellMobile takes no arguments; it reads AppShell context.
+  ],
+  returns: [
+    {
+      name: 'isMobile',
+      type: 'boolean',
+      description:
+        'Whether the current viewport is below the AppShell mobile navigation breakpoint. Use this to synchronize AppShell-adjacent mobile UI with the same breakpoint as mobile nav.',
+    },
+    {
+      name: 'isMobileNavOpen',
+      type: 'boolean',
+      description:
+        'Whether the AppShell-managed mobile navigation drawer is open.',
+    },
+    {
+      name: 'toggleMobileNav',
+      type: '() => void',
+      description:
+        'Toggle the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled.',
+    },
+    {
+      name: 'openMobileNav',
+      type: '() => void',
+      description:
+        'Open the AppShell-managed mobile navigation drawer. No-ops when mobile nav is disabled.',
+    },
+    {
+      name: 'closeMobileNav',
+      type: '() => void',
+      description: 'Close the AppShell-managed mobile navigation drawer.',
+    },
+    {
+      name: 'isMobileNavEnabled',
+      type: 'boolean',
+      description:
+        'Whether AppShell mobile navigation is enabled and managed by AppShell. False when mobileNav is false, there is no nav content, or a fully custom mobileNav ReactNode owns the drawer.',
+    },
+    {
+      name: 'hasAutoToggle',
+      type: 'boolean',
+      description:
+        'Whether AppShell auto-toggle behavior is enabled. False when mobileNav hasToggle is set to false; combine with isMobile and isMobileNavEnabled before rendering custom toggles.',
+    },
+  ],
+  usage: {
+    description:
+      'Hook for reading and controlling AppShell mobile navigation state from descendants of AppShell. Use it for custom mobile nav triggers, closing the drawer after route changes, or coordinating AppShell-adjacent mobile experiences with the same breakpoint used by mobile nav.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use inside the AppShell tree when building custom mobile navigation controls, route-aware nav items, or UI that should update at the same breakpoint as AppShell mobile nav.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer MobileNavToggle for the standard hamburger trigger: use this hook when you need custom placement, styling, or extra behavior.',
+      },
+      {
+        guidance: true,
+        description:
+          'Call closeMobileNav after a custom mobile nav item changes route so the drawer dismisses cleanly.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use as a general responsive primitive when the UI is not inside AppShell or does not need to align with AppShell mobile nav: use useMediaQuery instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume it throws outside AppShell. The hook returns safe defaults and no-op callbacks when no provider is present.',
+      },
+    ],
+  },
+  relatedComponents: [
+    'AppShell',
+    'MobileNav',
+    'MobileNavToggle',
+    'TopNav',
+    'SideNav',
+  ],
+  relatedHooks: ['useMediaQuery'],
+  importPath: '@astryxdesign/core/AppShell',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Reads/controls AppShell mobile nav context. Use for custom triggers, closing drawer after route changes, or syncing AppShell-adjacent mobile UI to the same breakpoint as mobile nav.',
+  returnDescriptions: {
+    isMobile:
+      'viewport below AppShell mobile nav breakpoint? Use to sync AppShell-adjacent mobile UI',
+    isMobileNavOpen: 'AppShell-managed mobile nav drawer open?',
+    toggleMobileNav: 'toggle drawer; no-op when mobile nav disabled',
+    openMobileNav: 'open drawer; no-op when mobile nav disabled',
+    closeMobileNav: 'close drawer',
+    isMobileNavEnabled:
+      'AppShell owns mobile nav? false when mobileNav=false, no nav content, or custom ReactNode owns drawer',
+    hasAutoToggle:
+      'auto-toggle enabled? false when mobileNav.hasToggle=false; combine w/ isMobile + isMobileNavEnabled before custom toggle render',
+  },
+  usage: {
+    description:
+      'Reads/controls AppShell mobile nav context. Use for custom triggers, closing drawer after route changes, or syncing AppShell-adjacent mobile UI to the same breakpoint as mobile nav.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use inside AppShell tree for custom nav controls, route-aware nav items, or UI that should update at AppShell mobile nav breakpoint.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer MobileNavToggle for standard hamburger; use hook for custom placement, styling, or extra behavior.',
+      },
+      {
+        guidance: true,
+        description:
+          'Call closeMobileNav after custom mobile nav item changes route so drawer dismisses.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use as general responsive primitive when not inside AppShell / not aligning to AppShell mobile nav: use useMediaQuery instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume it throws outside AppShell. Hook returns safe defaults + no-op callbacks without provider.',
+      },
+    ],
+  },
+};

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'AspectRatio',
+  displayName: 'Aspect Ratio',
+  category: 'Layout',
+  keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
+  usage: {
+    description:
+      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+    bestPractices: [
+      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
+      {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+    ],
+  },
+  props: [
+    {
+      name: 'ratio',
+      type: 'number',
+      description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+      required: true,
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Content positioned absolutely to fill the container.',
+      required: true,
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
+  ],
+  playground: {
+    defaults: {
+      ratio: 16 / 9,
+      children: {__element: 'Center', props: {height: '100%'}, children: {__element: 'Text', props: {color: 'secondary'}, children: '16:9'}},
+    },
+  },
+  theming: {
+    targets: [
+      {className: 'astryx-aspect-ratio'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'AspectRatio',
+  displayName: 'Aspect Ratio',
+  usage: {
+    description:
+      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+    bestPractices: [
+      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
+      {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+    ],
+  },
+  props: [
+    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {name: 'children', type: 'ReactNode', description: '通过绝对定位填充容器的内容。', required: true},
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于布局自定义的 StyleX 样式（外边距、定位、尺寸）。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-aspect-ratio'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'maintains specific aspect ratio for children',
+  usage: {
+    description:
+      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+    bestPractices: [
+      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
+      {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+    ],
+  },
+  propDescriptions: {
+    ratio: 'width/height ratio (e.g. 16/9, 1)',
+    children: 'content positioned absolutely to fill container',
+    xstyle: 'StyleX layout customization via stylex.create()',
+  },
+};

package/src/AspectRatio/AspectRatio.test.tsx

@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AspectRatio.test.tsx
+ * @input Uses vitest, @testing-library/react, AspectRatio component
+ * @output Unit tests for AspectRatio component behavior
+ * @position Testing; validates AspectRatio.tsx implementation
+ *
+ * SYNC: When AspectRatio.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {AspectRatio} from './AspectRatio';
+
+describe('AspectRatio', () => {
+  it('renders with correct aspect ratio', () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-testid="aspect-ratio">
+        <div>Content</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element).toBeInTheDocument();
+    expect(element.style.aspectRatio).toBe(String(16 / 9));
+  });
+
+  it('children fill the container', () => {
+    render(
+      <AspectRatio ratio={1} data-testid="aspect-ratio">
+        <div data-testid="child">Content</div>
+      </AspectRatio>,
+    );
+    const container = screen.getByTestId('aspect-ratio');
+    const child = screen.getByTestId('child');
+    expect(container).toContainElement(child);
+    // Child is wrapped in an absolute positioned div
+    const childWrapper = child.parentElement;
+    expect(childWrapper).not.toBeNull();
+  });
+
+  it('renders with 16:9 ratio', () => {
+    const ratio = 16 / 9;
+    render(
+      <AspectRatio ratio={ratio} data-testid="aspect-ratio">
+        <div>16:9</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe(String(ratio));
+  });
+
+  it('renders with 4:3 ratio', () => {
+    const ratio = 4 / 3;
+    render(
+      <AspectRatio ratio={ratio} data-testid="aspect-ratio">
+        <div>4:3</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe(String(ratio));
+  });
+
+  it('renders with 1:1 square ratio', () => {
+    render(
+      <AspectRatio ratio={1} data-testid="aspect-ratio">
+        <div>Square</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe('1');
+  });
+
+  it('renders with 21:9 ultrawide ratio', () => {
+    const ratio = 21 / 9;
+    render(
+      <AspectRatio ratio={ratio} data-testid="aspect-ratio">
+        <div>Ultrawide</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe(String(ratio));
+  });
+
+  it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
+    render(
+      <AspectRatio ratio={1} shape="ellipse" data-testid="aspect-ratio">
+        <div>Circle</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe('1');
+    expect(element.className).toContain('ellipse');
+  });
+
+  it('ellipse respects a non-square ratio (oval)', () => {
+    render(
+      <AspectRatio ratio={16 / 9} shape="ellipse" data-testid="aspect-ratio">
+        <div>Oval</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    // Ratio is preserved — the ellipse does not force 1:1.
+    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(element.className).toContain('ellipse');
+  });
+
+  it('defaults to the rectangle shape', () => {
+    render(
+      <AspectRatio ratio={1} data-testid="aspect-ratio">
+        <div>Rectangle by default</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element.style.aspectRatio).toBe('1');
+    expect(element.className).toContain('rectangle');
+    // No ellipse border-radius when shape is the default rectangle
+    expect(element.style.borderRadius).toBe('');
+  });
+
+  it('forwards ref correctly', () => {
+    const ref = vi.fn();
+    render(
+      <AspectRatio ratio={1} ref={ref}>
+        <div>Content</div>
+      </AspectRatio>,
+    );
+    expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
+  });
+
+  it('passes through additional props', () => {
+    render(
+      <AspectRatio
+        ratio={1}
+        data-testid="aspect-ratio"
+        aria-label="Image container">
+        <div>Content</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element).toHaveAttribute('aria-label', 'Image container');
+  });
+
+  it('renders with ReactNode children', () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-testid="aspect-ratio">
+        <img
+          src="test.jpg"
+          alt="Test"
+          data-testid="image"
+          style={{width: '100%', height: '100%', objectFit: 'cover'}}
+        />
+      </AspectRatio>,
+    );
+    const image = screen.getByTestId('image');
+    expect(image).toBeInTheDocument();
+  });
+
+  it('renders with xstyle prop', () => {
+    // Verify that xstyle is accepted and component renders without error
+    render(
+      <AspectRatio ratio={1} data-testid="aspect-ratio" xstyle={{}}>
+        <div>Content</div>
+      </AspectRatio>,
+    );
+    const element = screen.getByTestId('aspect-ratio');
+    expect(element).toBeInTheDocument();
+  });
+
+  it('renders different content types', () => {
+    render(
+      <AspectRatio ratio={16 / 9} data-testid="aspect-ratio">
+        <video data-testid="video" src="test.mp4" />
+      </AspectRatio>,
+    );
+    const video = screen.getByTestId('video');
+    expect(video).toBeInTheDocument();
+  });
+});

package/src/AspectRatio/AspectRatio.tsx

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file AspectRatio.tsx
+ * @input Uses React, stylex
+ * @output Exports AspectRatio component and AspectRatioProps
+ * @position AspectRatio component; maintains a specific aspect ratio for its children
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
+ * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
+ * - /apps/storybook/stories/AspectRatio.stories.tsx
+ * - /packages/cli/templates/blocks/components/AspectRatio/ (showcase blocks)
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
+
+/**
+ * The shape of the aspect ratio container.
+ * - `rectangle`: standard rectangular container (default).
+ * - `ellipse`: clips the container to an ellipse. Combined with the `ratio`,
+ *   this renders a circle at `ratio={1}` and an oval at non-square ratios.
+ */
+export type AspectRatioShape = 'rectangle' | 'ellipse';
+
+export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLDivElement>;
+  /**
+   * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+   */
+  ratio: number;
+
+  /**
+   * The shape of the container. Both shapes respect the provided `ratio`.
+   * - `rectangle` (default): a standard rectangular container.
+   * - `ellipse`: clips the container to an ellipse — a circle when `ratio={1}`,
+   *   or an oval at other ratios. Pair with a child that fills the container
+   *   (e.g. an image with `objectFit: 'cover'`).
+   *
+   * @default 'rectangle'
+   *
+   * @example
+   * ```
+   * <AspectRatio ratio={1} shape="ellipse">
+   *   <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+   * </AspectRatio>
+   * ```
+   */
+  shape?: AspectRatioShape;
+
+  /**
+   * Content to render inside the aspect ratio container.
+   * The child element will be positioned absolutely to fill the container.
+   */
+  children: ReactNode;
+}
+
+const styles = stylex.create({
+  container: {
+    position: 'relative',
+    width: '100%',
+    overflow: 'clip',
+    minHeight: 0,
+    flexShrink: 0,
+  },
+  ellipse: {
+    // 50% on both axes follows the box dimensions, so the clip respects the
+    // ratio: a circle at 1:1 and an oval at non-square ratios.
+    borderRadius: '50%',
+  },
+  child: {
+    position: 'absolute',
+    top: 0,
+    insetInlineStart: 0,
+    width: '100%',
+    height: '100%',
+  },
+});
+
+/**
+ * AspectRatio component for maintaining a specific aspect ratio for its children.
+ *
+ * Uses the CSS aspect-ratio property to maintain the ratio. The child element
+ * is positioned absolutely to fill the container, which is useful for images,
+ * videos, embeds, and placeholders.
+ *
+ * Use `shape="ellipse"` to clip the container into an ellipse — a circle at
+ * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
+ * `ratio`.
+ *
+ * @example
+ * ```
+ * <AspectRatio ratio={16 / 9}>
+ *   <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />
+ * </AspectRatio>
+ * ```
+ *
+ * @example
+ * ```
+ * <AspectRatio ratio={1} shape="ellipse">
+ *   <img src="avatar.jpg" alt="" style={{objectFit: 'cover'}} />
+ * </AspectRatio>
+ * ```
+ */
+export function AspectRatio({
+  ratio,
+  shape = 'rectangle',
+  children,
+  xstyle,
+  className,
+  style,
+  ref,
+  ...props
+}: AspectRatioProps) {
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(
+        themeProps('aspect-ratio', {shape}),
+        stylex.props(
+          styles.container,
+          shape === 'ellipse' && styles.ellipse,
+          xstyle,
+        ),
+        className,
+        {...style, aspectRatio: ratio},
+      )}
+      {...props}>
+      <div {...stylex.props(styles.child)}>{children}</div>
+    </div>
+  );
+}
+
+AspectRatio.displayName = 'AspectRatio';

package/src/AspectRatio/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from AspectRatio.tsx
+ * @output Exports AspectRatio component and props type
+ * @position Package entry point for AspectRatio
+ *
+ * SYNC: When modified, update /packages/core/src/AspectRatio/AspectRatio.doc.mjs
+ */
+
+export {AspectRatio} from './AspectRatio';
+export type {AspectRatioProps, AspectRatioShape} from './AspectRatio';