@fpkit/acss 3.0.0 → 3.1.1

package/src/components/flexbox/flex.types.ts

@@ -0,0 +1,243 @@
+/**
+ * Type definitions for Flex container components
+ * Supports responsive flexbox layouts with CSS custom properties
+ */
+
+/**
+ * Valid HTML elements for Flex container
+ * Restricted to semantic container elements only
+ */
+export type FlexContainerElement =
+  | "div"
+  | "section"
+  | "article"
+  | "aside"
+  | "main"
+  | "header"
+  | "footer"
+  | "nav"
+  | "ul"
+  | "ol"
+  | "dl"
+  | "li"
+  | "form"
+  | "fieldset";
+
+/**
+ * Valid HTML elements for Flex.Item
+ * Includes list item elements in addition to container elements
+ */
+export type FlexItemElement = FlexContainerElement | "li" | "dt" | "dd";
+
+/**
+ * Flex container direction
+ */
+export type FlexDirection = "row" | "row-reverse" | "column" | "column-reverse";
+
+/**
+ * Flex wrap behavior
+ */
+export type FlexWrap = "wrap" | "nowrap" | "wrap-reverse";
+
+/**
+ * Flex justify-content alignment
+ */
+export type FlexJustify =
+  | "start"
+  | "end"
+  | "center"
+  | "between"
+  | "around"
+  | "evenly";
+
+/**
+ * Flex align-items alignment
+ */
+export type FlexAlign = "start" | "end" | "center" | "baseline" | "stretch";
+
+/**
+ * Flex align-content alignment (multi-line)
+ */
+export type FlexAlignContent =
+  | "start"
+  | "end"
+  | "center"
+  | "between"
+  | "around"
+  | "evenly"
+  | "stretch";
+
+/**
+ * Flex align-self alignment (individual items)
+ */
+export type FlexAlignSelf =
+  | "auto"
+  | "start"
+  | "end"
+  | "center"
+  | "baseline"
+  | "stretch";
+
+/**
+ * Gap size options
+ */
+export type FlexGap = "0" | "xs" | "sm" | "md" | "lg" | "xl";
+
+/**
+ * Preset flex layout variants
+ */
+export type FlexVariant = "center" | "between" | "around" | "stack" | "spread";
+
+/**
+ * Responsive flex properties for breakpoints
+ */
+export interface ResponsiveFlexProps {
+  /** Flex direction */
+  direction?: FlexDirection;
+  /** Flex wrap behavior */
+  wrap?: FlexWrap;
+  /** Gap between flex items */
+  gap?: FlexGap;
+  /** Row gap (vertical spacing) */
+  rowGap?: FlexGap;
+  /** Column gap (horizontal spacing) */
+  colGap?: FlexGap;
+  /** Justify content (main axis alignment) */
+  justify?: FlexJustify;
+  /** Align items (cross axis alignment) */
+  align?: FlexAlign;
+  /** Align content (multi-line alignment) */
+  alignContent?: FlexAlignContent;
+}
+
+/**
+ * Base Flex component props
+ *
+ * ## Semantic Elements Only
+ * The `as` prop is restricted to semantic container elements to ensure
+ * proper HTML structure and accessibility. Use only block-level container
+ * elements like div, section, article, or form elements.
+ *
+ * **Allowed elements**: div, section, article, aside, main, header, footer,
+ * nav, ul, ol, dl, form, fieldset
+ *
+ * **Not allowed**: span, a, button, input, or other inline/interactive elements
+ */
+export interface FlexProps
+  extends ResponsiveFlexProps,
+    Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /** Preset layout variant */
+  variant?: FlexVariant;
+  /** Use inline-flex instead of flex */
+  inline?: boolean;
+  /**
+   * Element type to render as
+   * @remarks Restricted to semantic container elements only for proper HTML structure
+   */
+  as?: FlexContainerElement;
+  /** Additional CSS class names */
+  className?: string;
+  /** Inline styles and CSS custom properties */
+  styles?: React.CSSProperties;
+  /** Children elements */
+  children?: React.ReactNode;
+  /** Responsive props for small screens (≥30rem / 480px) */
+  sm?: ResponsiveFlexProps;
+  /** Responsive props for medium screens (≥48rem / 768px) */
+  md?: ResponsiveFlexProps;
+  /** Responsive props for large screens (≥62rem / 992px) */
+  lg?: ResponsiveFlexProps;
+  /** Responsive props for extra large screens (≥80rem / 1280px) */
+  xl?: ResponsiveFlexProps;
+}
+
+/**
+ * Flex.Item component props
+ *
+ * ## Semantic Elements
+ * The `as` prop accepts container elements plus list item elements (li, dt, dd)
+ * to support semantic list structures within flex containers.
+ *
+ * **Allowed elements**: div, section, article, aside, main, header, footer,
+ * nav, ul, ol, dl, form, fieldset, li, dt, dd
+ */
+export interface FlexItemProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /** Flex grow factor */
+  grow?: 0 | 1;
+  /** Flex shrink factor */
+  shrink?: 0 | 1;
+  /** Flex basis */
+  basis?: "auto" | "0" | "full";
+  /** Flex shorthand: '1' | 'auto' | 'initial' | 'none' */
+  flex?: "1" | "auto" | "initial" | "none";
+  /** Align self (overrides parent align-items) */
+  alignSelf?: FlexAlignSelf;
+  /** Order of the flex item */
+  order?: "first" | "last" | "none";
+  /**
+   * Element type to render as
+   * @remarks Includes list item elements (li, dt, dd) in addition to container elements
+   */
+  as?: FlexItemElement;
+  /** Additional CSS class names */
+  className?: string;
+  /** Inline styles and CSS custom properties */
+  styles?: React.CSSProperties;
+  /** Children elements */
+  children?: React.ReactNode;
+  /** Responsive props for small screens (≥30rem / 480px) */
+  sm?: {
+    flex?: "1" | "auto" | "none";
+  };
+  /** Responsive props for medium screens (≥48rem / 768px) */
+  md?: {
+    flex?: "1" | "auto" | "none";
+  };
+  /** Responsive props for large screens (≥62rem / 992px) */
+  lg?: {
+    flex?: "1" | "auto" | "none";
+  };
+  /** Responsive props for extra large screens (≥80rem / 1280px) */
+  xl?: {
+    flex?: "1" | "auto" | "none";
+  };
+}
+
+/**
+ * Flex.Spacer component props
+ * Creates an auto-expanding spacer element (flex: 1)
+ *
+ * ## Semantic Elements Only
+ * The `as` prop is restricted to container elements. Spacers are purely
+ * presentational and should use non-semantic containers like div.
+ *
+ * **Allowed elements**: div, section, article, aside, main, header, footer,
+ * nav, ul, ol, dl, form, fieldset
+ */
+export interface FlexSpacerProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /**
+   * Element type to render as
+   * @remarks Restricted to container elements. Default is 'div'.
+   */
+  as?: FlexContainerElement;
+  /** Additional CSS class names */
+  className?: string;
+  /** Inline styles and CSS custom properties */
+  styles?: React.CSSProperties;
+}
+
+/**
+ * Combined Flex component type with sub-components
+ */
+export type FlexComponent = React.ForwardRefExoticComponent<
+  FlexProps & React.RefAttributes<HTMLElement>
+> & {
+  Item: React.ForwardRefExoticComponent<
+    FlexItemProps & React.RefAttributes<HTMLElement>
+  >;
+  Spacer: React.ForwardRefExoticComponent<
+    FlexSpacerProps & React.RefAttributes<HTMLElement>
+  >;
+};

package/src/components/icons/components/arrow-right.tsx

@@ -2,11 +2,6 @@ import { IconProps } from '../types'
 import React from 'react'
 import Svg from './svg'
 
-const defaultStyles = {
-  ...Svg.styles,
-  fill: 'currentColor',
-}
-
 /*
  * ArrowRight icon component.
  *

package/src/components/kit.tsx

@@ -20,13 +20,13 @@ type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P)
 
 type PolymorphicComponentProp<
   C extends React.ElementType,
-  Props = {},
+  Props = object,
 > = React.PropsWithChildren<Props & AsProp<C>> &
   Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>
 
 type PolymorphicComponentPropWithRef<
   C extends React.ElementType,
-  Props = {},
+  Props = object,
 > = PolymorphicComponentProp<C, Props> & { ref?: PolymorphicRef<C> }
 
 type TextProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
@@ -36,9 +36,9 @@ type TextProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
 
 type TextComponent = <C extends React.ElementType = 'span'>(
   props: TextProps<C>,
-) => React.ReactElement | any
+) => React.ReactElement | null
 
-export const Text: TextComponent = React.forwardRef(
+const TextRef = React.forwardRef(
   <C extends React.ElementType = 'span'>(
     { as, color, children }: TextProps<C>,
     ref?: PolymorphicRef<C>,
@@ -54,3 +54,7 @@ export const Text: TextComponent = React.forwardRef(
     )
   },
 )
+
+TextRef.displayName = 'Text'
+
+export const Text = TextRef as unknown as TextComponent

package/src/components/link/link.tsx

@@ -176,7 +176,7 @@ export const LinkButton = React.forwardRef<HTMLAnchorElement, LinkProps>(
   ({ href, children, ...props }, ref) => {
     return (
       <Link ref={ref} href={href} {...props}>
-        {children}
+        <i>{children}</i>
       </Link>
     );
   }

package/src/components/popover/popover.tsx

@@ -10,7 +10,7 @@ import usePopover from '#hooks/popover/use-popover'
 export type PopoverProps = {
   children: React.ReactNode
   popoverTrigger: React.ReactNode
-  styles?: {}
+  styles?: React.CSSProperties
 }
 
 export const defaultStyles = {

package/src/components/tables/table-elements.tsx

@@ -35,7 +35,7 @@ export const Td = ({ children, ...props }: ComponentProps) => (
   </FP>
 )
 
-export const Table = ({ id, dataStyle, children, ...props }: ComponentProps) => {
+export const Table = ({ id, children, ...props }: ComponentProps) => {
   return (
     <FP
       as="section"

package/src/components/tables/table.tsx

@@ -1,4 +1,4 @@
-import { Table, Caption, Thead, Tbody, Td, Tr } from './table-elements'
+import { Table, Caption, Thead, Tbody, Tr } from './table-elements'
 import { ComponentProps } from '../../types'
 
 import React from 'react'
@@ -24,7 +24,7 @@ export const RenderHead = (data: []) => {
 /**
  * Render the table body `tr`, `td` with the data provided
  */
-export const RenderBody = (data: {}[]) => {
+export const RenderBody = (data: Record<string, unknown>[]) => {
   const rec = data.map((item, index) => {
     return (
       <tr key={index}>

package/src/components/text-to-speech/TextToSpeech.tsx

@@ -37,7 +37,6 @@ export const TextToSpeech: React.FC<TextToSpeechComponentProps> = ({
   voice,
   pitch = 1,
   rate = 1,
-  language,
   label,
   onEnd,
 }) => {
@@ -48,11 +47,8 @@ export const TextToSpeech: React.FC<TextToSpeechComponentProps> = ({
     cancel,
     isSpeaking,
     isPaused,
-    getAvailableLanguages,
-    availableVoices,
   } = useTextToSpeech()
   const [text, setText] = useState<string>(initialText)
-  console.log(getAvailableLanguages())
 
   useEffect(() => {
     setText(initialText)

package/src/components/text-to-speech/useTextToSpeech.tsx

@@ -32,9 +32,6 @@ export const useTextToSpeech = (initialVoice?: SpeechSynthesisVoice) => {
 
   const [isSpeaking, setIsSpeaking] = useState<boolean>(false)
   const [isPaused, setIsPaused] = useState<boolean>(false)
-  const [utterance, setUtterance] = useState<SpeechSynthesisUtterance | null>(
-    null,
-  )
 
   useEffect(() => {
     const updateVoices = () => {
@@ -103,12 +100,11 @@ export const useTextToSpeech = (initialVoice?: SpeechSynthesisVoice) => {
 
     if ('speechSynthesis' in window) {
       window.speechSynthesis.speak(utterance)
-      setUtterance(utterance)
       setIsSpeaking(true)
       setIsPaused(false)
     } else {
-      console.error('Speech synthesis not supported')
-      // Handle the error appropriately
+      // Speech synthesis not supported - silently skip
+      setIsSpeaking(false)
     }
   }
 

package/src/decorators/instructions.tsx

@@ -21,24 +21,28 @@ import UI from "#components/ui";
  * ```
  */
 export const WithInstructions =
-  (instructions?: React.ReactNode, title?: string) => (Story: StoryFn) => {
-    return (
-      <UI
-        style={{
-          paddingBlock: "2rem",
-          display: "flex",
-          flexDirection: "column",
-          gap: "3rem",
-          width: "max(320px, 90%)",
-        }}
-      >
-        <Story />
-        <div style={{ paddingInline: "1rem" }}>
-          <h3>{title || "Story Instructions"}</h3>
-          {instructions}
-        </div>
-      </UI>
-    );
+  (instructions?: React.ReactNode, title?: string) => {
+    const DecoratorComponent = (Story: StoryFn) => {
+      return (
+        <UI
+          style={{
+            paddingBlock: "2rem",
+            display: "flex",
+            flexDirection: "column",
+            gap: "3rem",
+            width: "max(320px, 90%)",
+          }}
+        >
+          <Story />
+          <div style={{ paddingInline: "1rem" }}>
+            <h3>{title || "Story Instructions"}</h3>
+            {instructions}
+          </div>
+        </UI>
+      );
+    };
+    DecoratorComponent.displayName = 'WithInstructionsDecorator';
+    return DecoratorComponent;
   };
 
 export default WithInstructions;

package/src/hooks/popover/popover.tsx

@@ -28,7 +28,7 @@ export type PopoverProps = {
  *
  * Transforms and opacity animate the popover enter/exit.
  */
-export const Popover = ({ children, ...props }: PopoverProps) => {
+export const Popover = ({ children }: PopoverProps) => {
   const hoverRef = React.useRef(null)
   const popOverRef = React.useRef(null)
   const { isVisible, popoverPosition, handlePointerEvent, handlePointerLeave } =

package/src/index.scss

@@ -22,4 +22,5 @@
 @use "./components/list/list.scss";
 @use "./components/alert/alert.scss";
 @use "./components/text-to-speech/text-to-speech.scss";
+@use "./components/flexbox/flex.scss";
 @use "./sass/styles";

package/src/index.ts

@@ -34,6 +34,23 @@ export { TextToSpeech } from "./components/text-to-speech/TextToSpeech";
 
 // Layout components
 export * from "./components/layout/landmarks";
+export { default as Flex } from "./components/flexbox/flex";
+export type {
+  FlexProps,
+  FlexItemProps,
+  FlexSpacerProps,
+  FlexContainerElement,
+  FlexItemElement,
+  FlexDirection,
+  FlexWrap,
+  FlexJustify,
+  FlexAlign,
+  FlexAlignContent,
+  FlexAlignSelf,
+  FlexGap,
+  FlexVariant,
+  ResponsiveFlexProps,
+} from "./components/flexbox/flex.types";
 
 // Navigation components
 export * from "./components/nav/nav";