@kaizen/components 0.0.0-canary-useContainerQueries-20251121043854 → 0.0.0-canary-useContainerQueries-20251125215952

package/dist/types/utils/useContainerQueries.d.ts

@@ -1,91 +0,0 @@
-import React, { type ReactNode } from 'react';
-type Props = Record<string, string>;
-type GenericChildrenType = {
-    children?: ReactNode;
-};
-type ContainerQueries = {
-    isXs: boolean;
-    isSm: boolean;
-    isMd: boolean;
-    isLg: boolean;
-    isXl: boolean;
-    is2xl: boolean;
-    is3xl: boolean;
-    is4xl: boolean;
-    is5xl: boolean;
-    is6xl: boolean;
-    is7xl: boolean;
-    [key: string]: boolean;
-};
-type ContainerComponents = {
-    'XsOnly': (props: GenericChildrenType) => JSX.Element;
-    'SmOnly': (props: GenericChildrenType) => JSX.Element;
-    'MdOnly': (props: GenericChildrenType) => JSX.Element;
-    'LgOnly': (props: GenericChildrenType) => JSX.Element;
-    'XlOnly': (props: GenericChildrenType) => JSX.Element;
-    '2xlOnly': (props: GenericChildrenType) => JSX.Element;
-    '3xlOnly': (props: GenericChildrenType) => JSX.Element;
-    '4xlOnly': (props: GenericChildrenType) => JSX.Element;
-    '5xlOnly': (props: GenericChildrenType) => JSX.Element;
-    '6xlOnly': (props: GenericChildrenType) => JSX.Element;
-    '7xlOnly': (props: GenericChildrenType) => JSX.Element;
-    'XsOrLarger': (props: GenericChildrenType) => JSX.Element;
-    'SmOrLarger': (props: GenericChildrenType) => JSX.Element;
-    'MdOrLarger': (props: GenericChildrenType) => JSX.Element;
-    'LgOrLarger': (props: GenericChildrenType) => JSX.Element;
-    'XlOrLarger': (props: GenericChildrenType) => JSX.Element;
-    [key: string]: (props: GenericChildrenType) => JSX.Element;
-};
-/**
- * A React hook for responding to container size changes using Tailwind CSS container query breakpoints.
- *
- * This hook uses ResizeObserver to detect when a container element crosses breakpoint thresholds,
- * enabling component-level responsive behavior independent of viewport size.
- *
- * @param propQueries - Optional custom container size queries in the format { queryName: 'minWidth' }
- *                      Example: { large: '600px', extraLarge: '48rem' }
- *
- * @returns An object containing:
- *   - containerRef: A ref to attach to your container element
- *   - queries: Boolean flags for each breakpoint (isXs, isSm, isMd, etc.) and custom queries
- *   - components: React components for conditional rendering (XsOnly, SmOrLarger, etc.)
- *
- * @example
- * ```tsx
- * const MyComponent = () => {
- *   const { containerRef, queries, components } = useContainerQueries()
- *   const { MdOrLarger } = components
- *
- *   return (
- *     <div ref={containerRef}>
- *       {queries.isSm && <p>Small container</p>}
- *       <MdOrLarger>
- *         <p>Medium or larger container</p>
- *       </MdOrLarger>
- *     </div>
- *   )
- * }
- * ```
- *
- * @example With custom queries
- * ```tsx
- * const { containerRef, queries, components } = useContainerQueries({
- *   compact: '400px',
- *   spacious: '800px',
- * })
- * const { Compact, Spacious } = components
- *
- * return (
- *   <div ref={containerRef}>
- *     <Compact><p>Compact view</p></Compact>
- *     <Spacious><p>Spacious view</p></Spacious>
- *   </div>
- * )
- * ```
- */
-export declare const useContainerQueries: (propQueries?: Props) => {
-    containerRef: React.RefCallback<HTMLElement>;
-    queries: ContainerQueries;
-    components: ContainerComponents;
-};
-export {};

package/src/utils/useContainerQueries.spec.tsx

@@ -1,242 +0,0 @@
-import React from 'react'
-import { act, render, screen } from '@testing-library/react'
-import { vi } from 'vitest'
-import { useContainerQueries } from './useContainerQueries'
-
-const ExampleComponent = (): JSX.Element => {
-  const { containerRef, queries, components } = useContainerQueries({
-    compact: '400px',
-    wide: '800px',
-  })
-  const { MdOrLarger, Compact } = components
-
-  return (
-    <div ref={containerRef} data-testid="container">
-      {queries.isSm && <button type="button">Small query boolean</button>}
-      <MdOrLarger>
-        <button type="button">Medium or larger component</button>
-      </MdOrLarger>
-      {queries.compact && <button type="button">Compact query boolean</button>}
-      <Compact>
-        <button type="button">Compact component</button>
-      </Compact>
-    </div>
-  )
-}
-
-// Mock ResizeObserver
-class ResizeObserverMock {
-  callback: ResizeObserverCallback
-  elements: Set<Element>
-
-  constructor(callback: ResizeObserverCallback) {
-    this.callback = callback
-    this.elements = new Set()
-  }
-
-  observe(target: Element): void {
-    this.elements.add(target)
-  }
-
-  unobserve(target: Element): void {
-    this.elements.delete(target)
-  }
-
-  disconnect(): void {
-    this.elements.clear()
-  }
-
-  // Helper method to trigger resize
-  trigger(width: number): void {
-    const entries: ResizeObserverEntry[] = Array.from(this.elements).map((element) => ({
-      target: element,
-      contentRect: {
-        width,
-        height: 100,
-        top: 0,
-        left: 0,
-        bottom: 100,
-        right: width,
-        x: 0,
-        y: 0,
-      } as DOMRectReadOnly,
-      borderBoxSize: [
-        {
-          inlineSize: width,
-          blockSize: 100,
-        },
-      ],
-      contentBoxSize: [
-        {
-          inlineSize: width,
-          blockSize: 100,
-        },
-      ],
-      devicePixelContentBoxSize: [
-        {
-          inlineSize: width,
-          blockSize: 100,
-        },
-      ],
-    })) as ResizeObserverEntry[]
-
-    this.callback(entries, this as unknown as ResizeObserver)
-  }
-}
-
-let resizeObserverInstance: ResizeObserverMock | null = null
-
-const setupResizeObserver = (): ResizeObserverMock => {
-  const mockObserver = vi.fn((callback: ResizeObserverCallback) => {
-    resizeObserverInstance = new ResizeObserverMock(callback)
-    return resizeObserverInstance
-  })
-
-  global.ResizeObserver = mockObserver as unknown as typeof ResizeObserver
-
-  return resizeObserverInstance!
-}
-
-describe('useContainerQueries()', () => {
-  beforeEach(() => {
-    resizeObserverInstance = null
-  })
-
-  afterEach(() => {
-    vi.restoreAllMocks()
-  })
-
-  it('shows and hides content based on Tailwind container breakpoints', async () => {
-    setupResizeObserver()
-
-    // Mock getBoundingClientRect to return a small width initially
-    const mockGetBoundingClientRect = vi.fn(() => ({
-      width: 300,
-      height: 100,
-      top: 0,
-      left: 0,
-      bottom: 100,
-      right: 300,
-      x: 0,
-      y: 0,
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      toJSON: () => {},
-    }))
-    Element.prototype.getBoundingClientRect = mockGetBoundingClientRect
-
-    render(<ExampleComponent />)
-
-    // Initially at 300px, should not show sm (384px) or md (448px) content
-    expect(screen.queryByRole('button', { name: /Small query boolean/i })).not.toBeInTheDocument()
-    expect(
-      screen.queryByRole('button', { name: /Medium or larger component/i }),
-    ).not.toBeInTheDocument()
-
-    // Trigger resize to 400px (sm breakpoint is 384px)
-    await act(async () => {
-      resizeObserverInstance?.trigger(400)
-    })
-
-    expect(screen.queryByRole('button', { name: /Small query boolean/i })).toBeInTheDocument()
-    expect(
-      screen.queryByRole('button', { name: /Medium or larger component/i }),
-    ).not.toBeInTheDocument()
-
-    // Trigger resize to 500px (md breakpoint is 448px)
-    await act(async () => {
-      resizeObserverInstance?.trigger(500)
-    })
-
-    expect(screen.queryByRole('button', { name: /Small query boolean/i })).toBeInTheDocument()
-    expect(
-      screen.queryByRole('button', { name: /Medium or larger component/i }),
-    ).toBeInTheDocument()
-  })
-
-  it('shows and hides content based on custom queries', async () => {
-    setupResizeObserver()
-
-    const mockGetBoundingClientRect = vi.fn(() => ({
-      width: 300,
-      height: 100,
-      top: 0,
-      left: 0,
-      bottom: 100,
-      right: 300,
-      x: 0,
-      y: 0,
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      toJSON: () => {},
-    }))
-    Element.prototype.getBoundingClientRect = mockGetBoundingClientRect
-
-    render(<ExampleComponent />)
-
-    // Initially at 300px, custom 'compact' query (400px) should not match
-    expect(screen.queryByRole('button', { name: /Compact query boolean/i })).not.toBeInTheDocument()
-    expect(screen.queryByRole('button', { name: /Compact component/i })).not.toBeInTheDocument()
-
-    // Trigger resize to 450px (compact is 400px)
-    await act(async () => {
-      resizeObserverInstance?.trigger(450)
-    })
-
-    expect(screen.queryByRole('button', { name: /Compact query boolean/i })).toBeInTheDocument()
-    expect(screen.queryByRole('button', { name: /Compact component/i })).toBeInTheDocument()
-  })
-
-  it('returns SSR-safe defaults when window is undefined', () => {
-    // This test verifies the SSR code path exists
-    // In actual SSR environment, the hook returns safe defaults
-    expect(useContainerQueries).toBeDefined()
-  })
-
-  it('cleans up ResizeObserver on unmount', () => {
-    setupResizeObserver()
-
-    const mockGetBoundingClientRect = vi.fn(() => ({
-      width: 500,
-      height: 100,
-      top: 0,
-      left: 0,
-      bottom: 100,
-      right: 500,
-      x: 0,
-      y: 0,
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      toJSON: () => {},
-    }))
-    Element.prototype.getBoundingClientRect = mockGetBoundingClientRect
-
-    const { unmount } = render(<ExampleComponent />)
-
-    const disconnectSpy = vi.spyOn(resizeObserverInstance!, 'disconnect')
-
-    unmount()
-
-    expect(disconnectSpy).toHaveBeenCalled()
-  })
-
-  it('observes the container element', () => {
-    setupResizeObserver()
-
-    const mockGetBoundingClientRect = vi.fn(() => ({
-      width: 500,
-      height: 100,
-      top: 0,
-      left: 0,
-      bottom: 100,
-      right: 500,
-      x: 0,
-      y: 0,
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      toJSON: () => {},
-    }))
-    Element.prototype.getBoundingClientRect = mockGetBoundingClientRect
-
-    render(<ExampleComponent />)
-
-    // Verify that the ResizeObserver is observing the container
-    expect(resizeObserverInstance?.elements.size).toBe(1)
-  })
-})

package/src/utils/useContainerQueries.tsx

@@ -1,333 +0,0 @@
-/* eslint-disable react-hooks/rules-of-hooks */
-import React, { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
-
-type Props = Record<string, string>
-type GenericChildrenType = { children?: ReactNode }
-
-/**
- * Tailwind CSS default container query breakpoints
- * These match the default values from @tailwindcss/container-queries plugin
- */
-const DEFAULT_BREAKPOINTS = {
-  'xs': '20rem', // 320px
-  'sm': '24rem', // 384px
-  'md': '28rem', // 448px
-  'lg': '32rem', // 512px
-  'xl': '36rem', // 576px
-  '2xl': '42rem', // 672px
-  '3xl': '48rem', // 768px
-  '4xl': '56rem', // 896px
-  '5xl': '64rem', // 1024px
-  '6xl': '72rem', // 1152px
-  '7xl': '80rem', // 1280px
-} as const
-
-/**
- * Convert rem/px values to pixels for comparison
- */
-const parseBreakpointValue = (value: string): number => {
-  if (value.endsWith('rem')) {
-    return parseFloat(value) * 16 // Assuming 1rem = 16px
-  }
-  if (value.endsWith('px')) {
-    return parseFloat(value)
-  }
-  return parseFloat(value)
-}
-
-type HelperComponentProps = {
-  children?: ReactNode
-}
-
-type ContainerQueries = {
-  isXs: boolean
-  isSm: boolean
-  isMd: boolean
-  isLg: boolean
-  isXl: boolean
-  is2xl: boolean
-  is3xl: boolean
-  is4xl: boolean
-  is5xl: boolean
-  is6xl: boolean
-  is7xl: boolean
-  [key: string]: boolean
-}
-
-type ContainerComponents = {
-  'XsOnly': (props: GenericChildrenType) => JSX.Element
-  'SmOnly': (props: GenericChildrenType) => JSX.Element
-  'MdOnly': (props: GenericChildrenType) => JSX.Element
-  'LgOnly': (props: GenericChildrenType) => JSX.Element
-  'XlOnly': (props: GenericChildrenType) => JSX.Element
-  '2xlOnly': (props: GenericChildrenType) => JSX.Element
-  '3xlOnly': (props: GenericChildrenType) => JSX.Element
-  '4xlOnly': (props: GenericChildrenType) => JSX.Element
-  '5xlOnly': (props: GenericChildrenType) => JSX.Element
-  '6xlOnly': (props: GenericChildrenType) => JSX.Element
-  '7xlOnly': (props: GenericChildrenType) => JSX.Element
-  'XsOrLarger': (props: GenericChildrenType) => JSX.Element
-  'SmOrLarger': (props: GenericChildrenType) => JSX.Element
-  'MdOrLarger': (props: GenericChildrenType) => JSX.Element
-  'LgOrLarger': (props: GenericChildrenType) => JSX.Element
-  'XlOrLarger': (props: GenericChildrenType) => JSX.Element
-  [key: string]: (props: GenericChildrenType) => JSX.Element
-}
-
-/**
- * A React hook for responding to container size changes using Tailwind CSS container query breakpoints.
- *
- * This hook uses ResizeObserver to detect when a container element crosses breakpoint thresholds,
- * enabling component-level responsive behavior independent of viewport size.
- *
- * @param propQueries - Optional custom container size queries in the format { queryName: 'minWidth' }
- *                      Example: { large: '600px', extraLarge: '48rem' }
- *
- * @returns An object containing:
- *   - containerRef: A ref to attach to your container element
- *   - queries: Boolean flags for each breakpoint (isXs, isSm, isMd, etc.) and custom queries
- *   - components: React components for conditional rendering (XsOnly, SmOrLarger, etc.)
- *
- * @example
- * ```tsx
- * const MyComponent = () => {
- *   const { containerRef, queries, components } = useContainerQueries()
- *   const { MdOrLarger } = components
- *
- *   return (
- *     <div ref={containerRef}>
- *       {queries.isSm && <p>Small container</p>}
- *       <MdOrLarger>
- *         <p>Medium or larger container</p>
- *       </MdOrLarger>
- *     </div>
- *   )
- * }
- * ```
- *
- * @example With custom queries
- * ```tsx
- * const { containerRef, queries, components } = useContainerQueries({
- *   compact: '400px',
- *   spacious: '800px',
- * })
- * const { Compact, Spacious } = components
- *
- * return (
- *   <div ref={containerRef}>
- *     <Compact><p>Compact view</p></Compact>
- *     <Spacious><p>Spacious view</p></Spacious>
- *   </div>
- * )
- * ```
- */
-export const useContainerQueries = (
-  propQueries: Props = {},
-): {
-  containerRef: React.RefCallback<HTMLElement>
-  queries: ContainerQueries
-  components: ContainerComponents
-} => {
-  // SSR support - return safe defaults when window is undefined
-  if (typeof window === 'undefined') {
-    return {
-      // eslint-disable-next-line @typescript-eslint/no-empty-function
-      containerRef: () => {},
-      queries: {
-        isXs: false,
-        isSm: false,
-        isMd: false,
-        isLg: false,
-        isXl: false,
-        is2xl: false,
-        is3xl: false,
-        is4xl: false,
-        is5xl: false,
-        is6xl: false,
-        is7xl: true, // Default to largest for SSR
-      },
-      components: {
-        'XsOnly': () => <></>,
-        'SmOnly': () => <></>,
-        'MdOnly': () => <></>,
-        'LgOnly': () => <></>,
-        'XlOnly': () => <></>,
-        '2xlOnly': () => <></>,
-        '3xlOnly': () => <></>,
-        '4xlOnly': () => <></>,
-        '5xlOnly': () => <></>,
-        '6xlOnly': () => <></>,
-        '7xlOnly': (props: HelperComponentProps) => <>{props.children}</>,
-        'XsOrLarger': (props: HelperComponentProps) => <>{props.children}</>,
-        'SmOrLarger': (props: HelperComponentProps) => <>{props.children}</>,
-        'MdOrLarger': (props: HelperComponentProps) => <>{props.children}</>,
-        'LgOrLarger': (props: HelperComponentProps) => <>{props.children}</>,
-        'XlOrLarger': (props: HelperComponentProps) => <>{props.children}</>,
-      },
-    }
-  }
-
-  // Parse all breakpoints to pixel values for comparison
-  const breakpointsPx = useMemo(
-    () =>
-      Object.entries(DEFAULT_BREAKPOINTS).reduce(
-        (acc, [key, value]) => {
-          acc[key] = parseBreakpointValue(value)
-          return acc
-        },
-        {} as Record<string, number>,
-      ),
-    [],
-  )
-
-  // Parse custom queries
-  const customQueriesPx = useMemo(
-    () =>
-      Object.entries(propQueries).reduce(
-        (acc, [key, value]) => {
-          acc[key] = parseBreakpointValue(value)
-          return acc
-        },
-        {} as Record<string, number>,
-      ),
-    [propQueries],
-  )
-
-  // State to track container width
-  const [containerWidth, setContainerWidth] = useState<number>(0)
-
-  // ResizeObserver ref
-  const resizeObserverRef = useRef<ResizeObserver | null>(null)
-
-  // Callback ref for the container element
-  const containerRef = useCallback((node: HTMLElement | null) => {
-    // Cleanup previous observer
-    if (resizeObserverRef.current) {
-      resizeObserverRef.current.disconnect()
-      resizeObserverRef.current = null
-    }
-
-    if (node) {
-      // Create new ResizeObserver
-      resizeObserverRef.current = new ResizeObserver((entries) => {
-        for (const entry of entries) {
-          // Use borderBoxSize for more accurate measurements
-          const width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width
-          setContainerWidth(width)
-        }
-      })
-
-      resizeObserverRef.current.observe(node)
-
-      // Set initial width
-      const width = node.getBoundingClientRect().width
-      setContainerWidth(width)
-    }
-  }, [])
-
-  // Cleanup on unmount
-  useEffect(
-    () => () => {
-      if (resizeObserverRef.current) {
-        resizeObserverRef.current.disconnect()
-      }
-    },
-    [],
-  )
-
-  // Calculate breakpoint matches based on container width
-  const breakpointMatches = useMemo(
-    () => ({
-      isXs: containerWidth >= breakpointsPx.xs,
-      isSm: containerWidth >= breakpointsPx.sm,
-      isMd: containerWidth >= breakpointsPx.md,
-      isLg: containerWidth >= breakpointsPx.lg,
-      isXl: containerWidth >= breakpointsPx.xl,
-      is2xl: containerWidth >= breakpointsPx['2xl'],
-      is3xl: containerWidth >= breakpointsPx['3xl'],
-      is4xl: containerWidth >= breakpointsPx['4xl'],
-      is5xl: containerWidth >= breakpointsPx['5xl'],
-      is6xl: containerWidth >= breakpointsPx['6xl'],
-      is7xl: containerWidth >= breakpointsPx['7xl'],
-    }),
-    [containerWidth, breakpointsPx],
-  )
-
-  // Calculate custom query matches
-  const customMatches = useMemo(
-    () =>
-      Object.entries(customQueriesPx).reduce(
-        (acc, [key, value]) => {
-          acc[key] = containerWidth >= value
-          return acc
-        },
-        {} as Record<string, boolean>,
-      ),
-    [containerWidth, customQueriesPx],
-  )
-
-  // Helper function to check if container is at exact breakpoint (not larger)
-  const isExactBreakpoint = useCallback(
-    (breakpoint: keyof typeof breakpointsPx): boolean => {
-      const sortedBreakpoints = Object.entries(breakpointsPx).sort(([, a], [, b]) => a - b)
-      const currentIndex = sortedBreakpoints.findIndex(([key]) => key === breakpoint)
-      const nextBreakpoint = sortedBreakpoints[currentIndex + 1]
-
-      const minWidth = breakpointsPx[breakpoint]
-      const maxWidth = nextBreakpoint ? nextBreakpoint[1] : Infinity
-
-      return containerWidth >= minWidth && containerWidth < maxWidth
-    },
-    [containerWidth, breakpointsPx],
-  )
-
-  // Create helper components for Tailwind breakpoints
-  const components = useMemo(
-    () => ({
-      'XsOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('xs') && props.children}</>,
-      'SmOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('sm') && props.children}</>,
-      'MdOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('md') && props.children}</>,
-      'LgOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('lg') && props.children}</>,
-      'XlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('xl') && props.children}</>,
-      '2xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('2xl') && props.children}</>,
-      '3xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('3xl') && props.children}</>,
-      '4xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('4xl') && props.children}</>,
-      '5xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('5xl') && props.children}</>,
-      '6xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('6xl') && props.children}</>,
-      '7xlOnly': (props: HelperComponentProps) => <>{isExactBreakpoint('7xl') && props.children}</>,
-      'XsOrLarger': (props: HelperComponentProps) => (
-        <>{breakpointMatches.isXs && props.children}</>
-      ),
-      'SmOrLarger': (props: HelperComponentProps) => (
-        <>{breakpointMatches.isSm && props.children}</>
-      ),
-      'MdOrLarger': (props: HelperComponentProps) => (
-        <>{breakpointMatches.isMd && props.children}</>
-      ),
-      'LgOrLarger': (props: HelperComponentProps) => (
-        <>{breakpointMatches.isLg && props.children}</>
-      ),
-      'XlOrLarger': (props: HelperComponentProps) => (
-        <>{breakpointMatches.isXl && props.children}</>
-      ),
-      // Custom query components
-      ...Object.keys(customQueriesPx).reduce(
-        (acc, key) => {
-          const componentName = key.charAt(0).toUpperCase() + key.slice(1)
-          acc[componentName] = (props: HelperComponentProps): JSX.Element => (
-            <>{customMatches[key] && props.children}</>
-          )
-          return acc
-        },
-        {} as Record<string, (props: GenericChildrenType) => JSX.Element>,
-      ),
-    }),
-    [breakpointMatches, customMatches, isExactBreakpoint, customQueriesPx],
-  )
-
-  return {
-    containerRef,
-    queries: { ...breakpointMatches, ...customMatches },
-    components,
-  }
-}