@fpkit/acss 0.4.4

package/src/components/images/img.test.tsx

@@ -0,0 +1,43 @@
+import { Img } from './img'
+import React from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import jest from 'jest-mock'
+describe('Img', () => {
+  it('should render an img element with passed props', () => {
+    const src = 'test.jpg'
+    const alt = 'Test image'
+    const width = 100
+
+    const { container } = render(<Img src={src} alt={alt} width={width} />)
+
+    const img = screen.getByRole('img')
+    expect(img).toBeInTheDocument()
+    expect(img).toHaveAttribute('src', src)
+    expect(img).toHaveAttribute('alt', alt)
+    expect(img).toHaveAttribute('width', width.toString())
+  })
+
+  it('should apply default styles when renderStyles is true', () => {
+    const { container } = render(<Img src="" alt="" />)
+  })
+
+  it('should call imgError callback on error', () => {
+    const onError = jest.fn()
+    render(<Img src="bad.jpg" alt="" imgError={onError} />)
+
+    const img = screen.getByRole('img')
+    fireEvent.error(img)
+
+    expect(onError).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call imgLoaded callback on load', () => {
+    const onLoad = jest.fn()
+    render(<Img src="good.jpg" alt="" imgLoaded={onLoad} />)
+
+    const img = screen.getByRole('img')
+    fireEvent.load(img)
+
+    expect(onLoad).toHaveBeenCalledTimes(1)
+  })
+})

package/src/components/images/img.tsx

@@ -0,0 +1,93 @@
+import UI from '../ui'
+import React from 'react'
+/*
+ * ImageProps interface
+ *
+ * Extends ComponentProps and defines additional props for the Img component.
+ *
+ * @property {string} [src] - The image source URL
+ * @property {string} alt - Required alt text for image accessibility
+ * @property {number} width - Required width of image
+ * @property {number} [height] - Optional height of image
+ * @property {"eager" | "lazy"} [loading="lazy"] - Loading behavior
+ * @property {string} [placeholder] - Fallback placeholder image
+ * @property {"high" | "low"} [fetchpriority="low"] - Image fetch priority
+ * @property {"sync" | "async" | "auto"} [decoding="auto"] - Decode setting
+ * @property {function} [imgError] - Error callback
+ * @property {function} [imgLoaded] - Loaded callback
+ */
+export type ImageProps = React.ComponentProps<'img'> &
+  React.ComponentProps<typeof UI>
+
+/*
+ * Img component
+ *
+ * Renders an <img> element with custom props.
+ *
+ * @param {string} src - The image source URL.
+ * @param {string} alt - The alt text for the image.
+ * @param {number} [width=480] - The width of the image.
+ * @param {number} [height] - The height of the image.
+ * @param {Object} [styles] - Additional CSS styles to apply.
+ * @param {boolean} [renderStyles=true] - Whether to render the default styles.
+ * @param {"eager" | "lazy"} [loading="lazy"] - The loading attribute.
+ * @param {string} [placeholder] - A placeholder image URL.
+ * @param {"high" | "low"} [fetchpriority="low"] - The fetchpriority attribute.
+ * @param {"sync" | "async" | "auto"} [decoding="auto"] - The decoding attribute.
+ * @param {function} [imgLoaded] - Callback when image loads successfully.
+ * @param {function} [imgError] - Callback when image errors.
+ *
+ * @returns {JSX.Element} The Img component.
+ */
+export const Img = ({
+  src = '//',
+  alt,
+  width = 480,
+  height,
+  styles,
+  loading = 'lazy',
+  placeholder = `https://via.placeholder.com/${width}?text=PLACEHOLDER`,
+  fetchpriority = 'low',
+  decoding = 'auto',
+  imgLoaded,
+  imgError,
+  ...props
+}: ImageProps) => {
+  const handleImgError = (
+    e: React.SyntheticEvent<HTMLImageElement, Event>,
+  ): void => {
+    if (imgError) {
+      imgError?.(e)
+      return
+    }
+    if (e.currentTarget.src !== placeholder) {
+      e.currentTarget.src = placeholder
+    }
+  }
+
+  const handleImgLoad = (
+    e: React.SyntheticEvent<HTMLImageElement, Event>,
+  ): void => {
+    imgLoaded?.(e)
+  }
+
+  return (
+    <UI
+      as="img"
+      src={src}
+      alt={alt}
+      width={width}
+      height={height || 'auto'}
+      loading={loading}
+      style={styles}
+      onError={handleImgError}
+      onLoad={handleImgLoad}
+      fetchPriority={fetchpriority}
+      decoding={decoding}
+      {...props}
+    />
+  )
+}
+
+export default Img
+Img.displayName = 'Img'

package/src/components/kit.tsx

@@ -0,0 +1,56 @@
+import React from 'react'
+
+type Rainbow =
+  | 'red'
+  | 'orange'
+  | 'yellow'
+  | 'green'
+  | 'blue'
+  | 'indigo'
+  | 'violet'
+
+type PolymorphicRef<C extends React.ElementType> =
+  React.ComponentPropsWithRef<C>['ref']
+
+type AsProp<C extends React.ElementType> = {
+  as?: C
+}
+
+type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P)
+
+type PolymorphicComponentProp<
+  C extends React.ElementType,
+  Props = {},
+> = React.PropsWithChildren<Props & AsProp<C>> &
+  Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>
+
+type PolymorphicComponentPropWithRef<
+  C extends React.ElementType,
+  Props = {},
+> = PolymorphicComponentProp<C, Props> & { ref?: PolymorphicRef<C> }
+
+type TextProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
+  C,
+  { color?: Rainbow | 'black' }
+>
+
+type TextComponent = <C extends React.ElementType = 'span'>(
+  props: TextProps<C>,
+) => React.ReactElement | any
+
+export const Text: TextComponent = React.forwardRef(
+  <C extends React.ElementType = 'span'>(
+    { as, color, children }: TextProps<C>,
+    ref?: PolymorphicRef<C>,
+  ) => {
+    const Component = as || 'span'
+
+    const style = color ? { style: { color } } : {}
+
+    return (
+      <Component {...style} ref={ref}>
+        {children}
+      </Component>
+    )
+  },
+)

package/src/components/layout/_header.scss

@@ -0,0 +1,72 @@
+header,
+[data-hero],
+[data-grid~='overlay'] {
+  // Name of the grid area
+  --overlay-grid-area: overlay;
+  // Placement of items in grid area
+  --overlay-placement: center;
+  // Controls display of grid
+  --overlay-display: grid;
+  // Overlay padding
+  --overlay-padding: 2rem;
+  --overlay-w: 100%;
+  --overlay-h: 40vh;
+  --overlay-max-h: 500px;
+  --overlay-color: currentColor;
+  --overlay-content-w: 80%;
+  --overlay-gap: 2rem;
+  --overlay-bg: whitesmoke;
+  --overlay-px: auto;
+  --overlay-py: auto;
+  --overlay-mx: auto;
+  --overlay-my: auto;
+
+  grid-template-areas: 'overlay';
+  display: var(--overlay-display);
+  place-items: var(--overlay-placement);
+  align-items: var(--overlay-placement);
+  min-height: var(--overlay-h);
+  width: var(--overlay-w);
+  color: var(--overlay-color);
+  background-color: var(--overlay-bg);
+  min-width: 20rem;
+  > * {
+    grid-area: overlay;
+  }
+  > img {
+    width: var(--overlay-w);
+    // height: auto;
+    background-size: contain;
+  }
+  > div,
+  > section {
+    --overlay-display: flex;
+    max-width: var(--overlay-content-w);
+    padding-inline: var(--spc-4);
+    margin-inline: var(--overlay-mx);
+    gap: var(--overlay-gap);
+    text-align: center;
+    p {
+      width: auto;
+      max-width: 60ch;
+      font-size: var(--fs-8);
+      line-height: 1.4;
+    }
+    > h1,
+    > h2 {
+      line-height: var(--header-lh, 1.1);
+      font-weight: 500;
+    }
+
+    > h1 {
+      font-size: var(--fs-12);
+    }
+    > h2 {
+      font-size: var(--fs-11);
+    }
+    > h3 {
+      font-size: var(--fs-10);
+    }
+
+  }
+}

package/src/components/layout/footer.stories.tsx

@@ -0,0 +1,34 @@
+import { StoryObj, Meta } from '@storybook/react'
+/**
+ * Import testing library dependencies
+ */
+import { within, userEvent } from '@storybook/testing-library'
+
+/**
+ * Import jest matchers
+ */
+import { expect } from '@storybook/jest'
+
+import { Footer } from './landmarks'
+
+const meta: Meta<typeof Footer> = {
+  title: 'FP.React Components/Layout/Landmarks',
+  component: Footer,
+  args: {
+    children: 'Main Landmark',
+    // @ts-ignore
+    'data-testid': 'main',
+  },
+} as Meta
+
+const mainChildren = () => (
+  <>
+    <h2>Header Title</h2>
+    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Vero, unde?</p>
+  </>
+)
+
+export default meta
+type Story = StoryObj<typeof Footer>
+
+export const BasicFooter: Story = {}

package/src/components/layout/landmarks.scss

@@ -0,0 +1,51 @@
+@use './header';
+
+
+main,
+footer {
+  --content-w: min(100%, 1480px);
+  --content-mx: auto;
+  --content-px: 1rem;
+  --content-gap: 2rem;
+  padding-block: var(--overlay-padding);
+  > section {
+    width: var(--content-w);
+    margin-inline: var(--content-mx);
+    padding-inline: var(--spc-6);
+  }
+}
+
+main {
+  flex: 1;
+  font-size: var(--fs-3);
+  > section[aria-label],
+  > section {
+    width: var(--content-w);
+    margin-inline: var(--content-mx);
+    &:has(> article, > aside) {
+      display: flex;
+      flex-wrap: wrap;
+      flex: 1;
+      gap: var(--content-gap);
+      > article {
+        flex-basis: 0;
+        flex-grow: 999;
+        min-inline-size: 50%;
+      }
+      > aside {
+        flex-basis: 20rem;
+        flex-grow: 1;
+      }
+    }
+  }
+}
+
+footer {
+  > div {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 5rem;
+    text-align: center;
+  }
+}

package/src/components/layout/landmarks.stories.tsx

@@ -0,0 +1,54 @@
+import { StoryObj, Meta } from '@storybook/react'
+/**
+ * Import testing library dependencies
+ */
+import { within, userEvent } from '@storybook/testing-library'
+
+/**
+ * Import jest matchers
+ */
+import { expect } from '@storybook/jest'
+
+import { Header } from './landmarks'
+
+import Img from '#components/images/img'
+
+const meta: Meta<typeof Header> = {
+  title: 'FP.React Components/Layout/Landmarks',
+  component: Header,
+  args: {
+    children: 'Default Header',
+    // @ts-ignore
+    'data-testid': 'banner',
+  },
+} as Meta
+
+const headerChildren = () => (
+  <>
+    <h2>Header Title</h2>
+    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Vero, unde?</p>
+  </>
+)
+
+export default meta
+type Story = StoryObj<typeof Header>
+
+export const LandmarkDefault: Story = {}
+
+export const HeroHeader: Story = {
+  args: {
+    children: headerChildren(),
+    headerBackground: <Img src="https://picsum.photos/2000/1000" alt="" />,
+    styles: { color: 'red' },
+    classNames: 'header-class',
+    'data-styles': 'blue',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const header = canvas.getByRole('banner')
+    expect(header).toBeInTheDocument()
+    const title = canvas.getByRole('heading')
+    expect(title).toBeInTheDocument()
+    expect(title).toHaveTextContent(/header title/i)
+  },
+} as Story

package/src/components/layout/landmarks.tsx

@@ -0,0 +1,149 @@
+import UI from '../ui'
+import React, { ReactNode } from 'react'
+
+type ComponentProps = React.ComponentProps<typeof UI>
+
+/**
+ * Renders children elements without any wrapping component.
+ * Can be used as a placeholder when no semantic landmark is needed.
+ */
+export const Landmarks = (children?: React.FC) => <>{children}</>
+
+type HeaderProps = {
+  headerBackground?: ReactNode
+} & ComponentProps
+/**
+ * Header component.
+ *
+ * Renders a header landmark with a section child.
+ *
+ * @param children - The content to render inside the header.
+ * @param styles - Optional styles object.
+ * @param props - Other props.
+ */
+export const Header = ({
+  id,
+  children,
+  headerBackground,
+  styles,
+  classes,
+  ...props
+}: HeaderProps) => {
+  return (
+    <UI as="header" id={id} styles={styles} className={classes} {...props}>
+      {headerBackground}
+      <UI as="section">{children}</UI>
+    </UI>
+  )
+}
+
+/**
+ * Main component.
+ *
+ * Renders a main landmark.
+ *
+ * @param children - The content to render inside the main element.
+ * @param styles - Optional styles object.
+ * @param props - Other props.
+ */
+export const Main = ({
+  id,
+  children,
+  styles,
+  classes,
+  ...props
+}: ComponentProps) => {
+  return (
+    <UI as="main" id={id} styles={styles} {...props} className={classes}>
+      {children}
+    </UI>
+  )
+}
+
+/**
+ * Footer component that renders a footer element with a section element inside.
+ * @param {ReactNode} children - Child elements to render inside the section element.
+ * @param styles - CSS styles to apply to the footer element.
+ * @param props - Additional props to pass to the footer element.
+ * @returns A React component that renders a footer element with a section element inside.
+ */
+export const Footer = ({
+  id,
+  classes,
+  children,
+  styles = {},
+  ...props
+}: ComponentProps) => {
+  return (
+    <UI as="footer" id={id} className={classes} styles={styles} {...props}>
+      <UI as="section">{children || 'Copyright © 2022'}</UI>
+    </UI>
+  )
+}
+
+export const Aside = ({
+  id,
+  children,
+  styles = {},
+  classes,
+  ...props
+}: ComponentProps) => {
+  return (
+    <UI as="aside" id={id} styles={styles} className={classes} {...props}>
+      <UI as="section">{children}</UI>
+    </UI>
+  )
+}
+
+/**
+ * Section component that renders a section element.
+ *
+ * @param children - Child elements to render inside the section.
+ * @param styles - CSS styles to apply to the section.
+ * @param props - Other props.
+ */
+export const Section = ({
+  id,
+  children,
+  styles,
+  classes,
+  ...props
+}: ComponentProps) => {
+  return (
+    <UI as="section" id={id} styles={styles} className={classes} {...props}>
+      {children}
+    </UI>
+  )
+}
+
+/**
+ * Article component renders an HTML <article> element.
+ *
+ * @param children - Child elements to render inside the article.
+ * @param styles - CSS styles to apply to the article.
+ * @param props - Additional props to pass to the article element.
+ */
+export const Article = ({
+  id,
+  children,
+
+  styles,
+  classes,
+  ...props
+}: ComponentProps) => {
+  return (
+    <UI as="article" id={id} styles={styles} className={classes} {...props}>
+      {children}
+    </UI>
+  )
+}
+
+export default Landmarks
+
+Landmarks.displayName = 'Landmarks'
+Landmarks.Header = Header
+Landmarks.Main = Main
+Landmarks.Footer = Footer
+Landmarks.Aside = Aside
+Landmarks.Section = Section
+Landmarks.Article = Article

package/src/components/layout/main.stories.tsx

@@ -0,0 +1,90 @@
+import { StoryObj, Meta } from '@storybook/react'
+/**
+ * Import testing library dependencies
+ */
+import { within, userEvent } from '@storybook/testing-library'
+
+/**
+ * Import jest matchers
+ */
+import { expect } from '@storybook/jest'
+
+import { Main } from './landmarks'
+
+const meta: Meta<typeof Main> = {
+  title: 'FP.React Components/Layout/Landmarks',
+  component: Main,
+  args: {
+    // @ts-ignore
+    children: (
+      <section>
+        The main HTML element represents the dominant content of the body of a
+        document.
+      </section>
+    ),
+    // @ts-ignore
+    'data-testid': 'main',
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ minHeight: '80vh', display: 'flex' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} as Meta
+
+const mainChildren = () => (
+  <>
+    <section aria-label="main-content">
+      <article>
+        <h3>Header Title</h3>
+        <p>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Nobis alias,
+          labore quibusdam, culpa dolorum rerum fugiat laborum deserunt sed ad
+          eveniet, modi reprehenderit vero pariatur enim esse eaque consectetur
+          nulla.
+        </p>
+        <hr />
+        <p>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Nobis alias,
+          labore quibusdam, culpa dolorum rerum fugiat laborum deserunt sed ad
+          eveniet, modi reprehenderit vero pariatur enim esse eaque consectetur
+          nulla.
+        </p>
+        <div>Lorem ipsum dolor sit amet.</div>
+      </article>
+      <aside>
+        <p>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Vero, unde?
+        </p>
+      </aside>
+    </section>
+  </>
+)
+
+export default meta
+type Story = StoryObj<typeof Main>
+
+export const MainLandmark: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const main = canvas.getByRole('main')
+    expect(main).toBeInTheDocument()
+  },
+}
+
+export const MainArticles: Story = {
+  args: {
+    // @ts-ignore
+    children: mainChildren(),
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const main = canvas.getByRole('main')
+    expect(main).toBeInTheDocument()
+    const title = canvas.getByRole('heading')
+    expect(title).toBeInTheDocument()
+    expect(title).toHaveTextContent('Header Title')
+  },
+}