@fpkit/acss 0.4.4

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

@@ -0,0 +1,182 @@
+
+
+```bash
+npm install fpkit-react
+```
+
+## Usage
+
+To use the `useTextToSpeech` hook in your React application, follow these steps:
+
+1. Import the hook into your component:
+
+```jsx
+import { useTextToSpeech } from 'fpkit-react';
+```
+
+2. Initialize the hook:
+
+```jsx
+const { speak, speaking, paused, availableVoices, availableLanguages, cancel } = useTextToSpeech();
+```
+
+3. Use the hook's functions to control speech:
+
+```jsx
+speak('Hello, world!');
+```
+
+4. Customize speech options:
+
+```jsx
+speak('Hello, world!', {
+  voice: availableVoices[0],
+  language: availableLanguages[0],
+  pitch: 1,
+  rate: 1,
+});
+```
+
+5. Handle speaking and paused states:
+
+```jsx
+<div>
+  {speaking ? 'Speaking...' : 'Paused'}
+  <button onClick={cancel}>Cancel</button>
+</div>
+```
+
+## Example
+
+Here's a simple example that demonstrates the use of the `useTextToSpeech` hook:
+
+```jsx
+import React, { useState } from 'react';
+import { useTextToSpeech } from 'fpkit-react';
+
+const App = () => {
+  const { speak, speaking, paused, availableVoices, availableLanguages, cancel } = useTextToSpeech();
+  const [text, setText] = useState('');
+
+  return (
+    <div>
+      <input type="text" value={text} onChange={(e) => setText(e.target.value)} />
+      <button onClick={() => speak(text)}>Speak</button>
+      <button onClick={cancel}>Cancel</button>
+      <p>{speaking ? 'Speaking...' : paused ? 'Paused' : 'Not speaking'}</p>
+      <select>
+        {availableVoices.map((voice) => (
+          <option key={voice.name} value={voice.name}>
+            {voice.name}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default App;
+```
+
+This example creates a simple text-to-speech application with an input field, a speak button, a cancel button, and a dropdown menu to select voices.
+
+## API
+
+### `speak(text, options)`
+
+- `text`: The text to be spoken.
+- `options`: An object with the following optional properties:
+  - `voice`: The voice to use for the speech.
+  - `language`: The language to use for the speech.
+  - `pitch`: The pitch of the speech (0.1 to 2).
+  - `rate`: The rate of the speech (0.1 to 10).
+
+### `speaking`
+
+- A boolean value indicating whether the speech is currently being spoken.
+
+### `paused`
+
+- A boolean value indicating whether the speech is currently paused.
+
+### `availableVoices`
+
+- An array of available voices for the speech.
+
+### `availableLanguages`
+
+- An array of available languages for the speech.
+
+### `cancel()`
+
+- A function to cancel the speech.
+
+# useTextToSpeech Hook
+
+The `useTextToSpeech` hook provides a simple way to add text-to-speech capabilities to your React components.
+
+## API
+
+```typescript
+const {
+  speak,
+  pause,
+  resume,
+  cancel,
+  isSpeaking,
+  isPaused,
+  error
+} = useTextToSpeech(options);
+```
+
+### Parameters
+
+- `options` (optional): An object containing configuration options for the text-to-speech functionality.
+  - `rate` (optional): Speech rate (0.1 to 10). Default is 1.
+  - `pitch` (optional): Speech pitch (0 to 2). Default is 1.
+  - `volume` (optional): Speech volume (0 to 1). Default is 1.
+  - `voice` (optional): A `SpeechSynthesisVoice` object to use for speech.
+
+### Return Value
+
+- `speak`: Function to start speaking the provided text.
+- `pause`: Function to pause the current speech.
+- `resume`: Function to resume paused speech.
+- `cancel`: Function to cancel the current speech.
+- `isSpeaking`: Boolean indicating if speech is currently in progress.
+- `isPaused`: Boolean indicating if speech is currently paused.
+- `error`: Any error that occurred during speech synthesis.
+
+## Best Practices
+
+1. Always provide visual feedback about the current state (speaking, paused, idle).
+2. Handle errors gracefully and inform the user when something goes wrong.
+3. Use appropriate ARIA attributes for accessibility when implementing custom controls.
+4. Consider providing options to customize the voice, if supported by the browser.
+5. Test the component across different browsers and devices to ensure consistent behavior.
+
+---
+
+## Browser Support
+
+The text-to-speech functionality relies on the Web Speech API, which is supported in most modern browsers. However, it's always a good idea to check for compatibility and provide fallback content or functionality for unsupported browsers.
+
+## Notes
+
+- The `useTextToSpeech` hook requires a user gesture to be triggered, such as a button click.
+- The `availableVoices` and `availableLanguages` arrays are dynamically generated based on the browser's capabilities.
+- The `pitch` and `rate` values are normalized to a range of 0.1 to 2 and 0.1 to 10, respectively.
+
+## Browser Support
+
+The Web Speech API is supported in most modern browsers, including Chrome, Edge, and some versions of Firefox. However, the availability of voices and languages may vary by browser.
+
+## Contributing
+
+We welcome contributions to the FPKit React library. If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on our GitHub repository.
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for more details.
+
+

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

@@ -0,0 +1,176 @@
+import { useState, useEffect } from 'react'
+
+/**
+ * Options for configuring speech synthesis.
+ * @interface SpeechOptions
+ */
+interface SpeechOptions {
+  /** The language for speech synthesis (e.g., 'en-US') */
+  lang?: string
+
+  /** The pitch of the voice (0 to 2) */
+  pitch?: number
+  /** The speed of the voice (0.1 to 10) */
+  rate?: number
+
+  /** The voice to use for speech synthesis */
+  voice?: SpeechSynthesisVoice
+}
+/**
+ * Custom hook to handle text-to-speech functionality.
+ *
+ * @param {SpeechSynthesisVoice} [initialVoice] - The initial voice to use for speech synthesis.
+ * @returns {Object} An object containing methods to control speech synthesis and state variables.
+ */
+export const useTextToSpeech = (initialVoice?: SpeechSynthesisVoice) => {
+  const [availableVoices, setAvailableVoices] = useState<
+    SpeechSynthesisVoice[]
+  >([])
+  const [currentVoice, setCurrentVoice] = useState<
+    SpeechSynthesisVoice | undefined
+  >(initialVoice)
+
+  const [isSpeaking, setIsSpeaking] = useState<boolean>(false)
+  const [isPaused, setIsPaused] = useState<boolean>(false)
+  const [utterance, setUtterance] = useState<SpeechSynthesisUtterance | null>(
+    null,
+  )
+
+  useEffect(() => {
+    const updateVoices = () => {
+      const voices = window.speechSynthesis.getVoices()
+      setAvailableVoices(voices)
+
+      // Set default voice to Google US English if available
+      const googleVoice = voices.find(
+        (voice) => voice.name === 'Google US English',
+      )
+      if (googleVoice) {
+        setCurrentVoice(googleVoice)
+      } else {
+        // Fallback to the first English voice if Google voice is not available
+        const englishVoice = voices.find((voice) =>
+          voice.lang.startsWith('en-'),
+        )
+        if (englishVoice) {
+          setCurrentVoice(englishVoice)
+        }
+      }
+    }
+
+    updateVoices()
+    window.speechSynthesis.onvoiceschanged = updateVoices
+
+    return () => {
+      window.speechSynthesis.onvoiceschanged = null
+    }
+  }, [])
+
+  /**
+   * Gets the list of available languages for speech synthesis.
+   * @returns {string[]} An array of available language codes.
+   */
+  const getAvailableLanguages = () => {
+    return [...new Set(availableVoices.map((voice) => voice.lang))]
+  }
+
+  /**
+   * Initiates speech synthesis for the given text.
+   *
+   * @param {string} text - The text to be spoken.
+   * @param {SpeechOptions} [options={}] - Options for speech synthesis.
+   * @param {Function} [onEnd] - Callback function to be called when speech ends.
+   */
+  const speak = (
+    text: string,
+    options: SpeechOptions = {},
+    onEnd?: () => void,
+  ) => {
+    const utterance = new SpeechSynthesisUtterance(text)
+
+    utterance.lang = options.lang ?? 'en-US'
+    utterance.pitch = options.pitch ?? 1
+    utterance.rate = options.rate ?? 1
+    utterance.voice = currentVoice ?? options.voice ?? null
+
+    utterance.onend = () => {
+      setIsSpeaking(false)
+      setIsPaused(false)
+      if (onEnd) {
+        onEnd()
+      }
+    }
+
+    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
+    }
+  }
+
+  /**
+   * Changes the current voice used for speech synthesis.
+   * @param {SpeechSynthesisVoice} voice - The new voice to use.
+   */
+  const changeVoice = (voice: SpeechSynthesisVoice) => {
+    setCurrentVoice(voice)
+  }
+
+  /**
+   * Pauses the ongoing speech synthesis.
+   */
+  const pause = () => {
+    if (isSpeaking && !isPaused) {
+      window.speechSynthesis.pause()
+      setIsPaused(true)
+    }
+  }
+
+  /**
+   * Resumes the paused speech synthesis.
+   */
+  const resume = () => {
+    if (isSpeaking && isPaused) {
+      window.speechSynthesis.resume()
+      setIsPaused(false)
+    }
+  }
+
+  /**
+   * Cancels the ongoing speech synthesis.
+   */
+  const cancel = () => {
+    if (isSpeaking) {
+      window.speechSynthesis.cancel()
+      setIsSpeaking(false)
+      setIsPaused(false)
+    }
+  }
+
+  return {
+    /** Initiates speech synthesis for the given text */
+    speak,
+    /** Pauses the ongoing speech synthesis */
+    pause,
+    /** Resumes the paused speech synthesis */
+    resume,
+    /** Cancels the ongoing speech synthesis */
+    cancel,
+    /** Indicates whether speech synthesis is currently active */
+    isSpeaking,
+    /** Indicates whether speech synthesis is currently paused */
+    isPaused,
+    /** Array of available voices for speech synthesis */
+    availableVoices,
+    /** Changes the current voice used for speech synthesis */
+    changeVoice,
+    /** The currently selected voice for speech synthesis */
+    currentVoice,
+    /** Gets the list of available languages for speech synthesis */
+    getAvailableLanguages,
+  }
+}

package/src/components/text-to-speech/views/TextToSpeechControls.tsx

@@ -0,0 +1,117 @@
+import React from 'react'
+import Icon from '#components/icons/icon'
+import UI from '#components/ui'
+import { FC } from 'react'
+
+/**
+ * Props for the TextToSpeechControls component.
+ * @interface TextToSpeechControlsProps
+ */
+interface TextToSpeechControlsProps {
+  /** Optional label for the controls */
+  label?: string | React.ReactNode
+  /** Indicates if the text-to-speech is currently speaking */
+  isSpeaking: boolean
+  /** Indicates if the text-to-speech is paused */
+  isPaused: boolean
+  /** Function to start speaking */
+  onSpeak: () => void
+  /** Function to pause speaking */
+  onPause: () => void
+  /** Function to resume speaking */
+  onResume: () => void
+  /** Function to cancel speaking */
+  onCancel: () => void
+}
+
+/**
+ * TTSButtonComponent props
+ * @interface TTSButtonComponentProps
+ */
+interface TTSButtonComponentProps {
+  /** The content of the button */
+  children: React.ReactNode
+  /** Function to call when the button is clicked */
+  onClick: () => void
+}
+
+/**
+ * TTSButtonComponent is a reusable button component for text-to-speech controls.
+ * @param {TTSButtonComponentProps} props - The component props
+ * @returns {React.ReactElement} The rendered button
+ */
+export const TTSButtonComponent: React.FC<TTSButtonComponentProps> = ({
+  children,
+  onClick,
+}) => {
+  return (
+    <UI
+      as="button"
+      type="button"
+      className="tts-border"
+      data-btn="sm text pill"
+      onClick={onClick}
+    >
+      {children}
+    </UI>
+  )
+}
+
+export const TTSButton = React.memo(TTSButtonComponent)
+
+/**
+ * TextToSpeechControlsComponent interface extends FC<TextToSpeechControlsProps>
+ * and includes a TTSButton property.
+ * @interface TextToSpeechControlsComponent
+ * @extends {FC<TextToSpeechControlsProps>}
+ */
+interface TextToSpeechControlsComponent extends FC<TextToSpeechControlsProps> {
+  /** The TTSButton component used within TextToSpeechControls */
+  TTSButton: typeof TTSButton
+}
+
+/**
+ * TextToSpeechControls component provides a user interface for controlling text-to-speech functionality.
+ * @param {TextToSpeechControlsProps} props - The component props
+ * @returns {React.ReactElement} The rendered TextToSpeechControls component
+ */
+const TextToSpeechControls: TextToSpeechControlsComponent = ({
+  label,
+  isSpeaking,
+  isPaused,
+  onSpeak,
+  onPause,
+  onResume,
+  onCancel,
+}) => {
+  const iconSize = 16
+
+  return (
+    <UI as="div" data-tts>
+      {label && <p>{label}</p>}
+      {!isSpeaking && (
+        <TTSButton aria-label="Speak" onClick={onSpeak}>
+          <Icon.PlaySolid size={iconSize} />
+        </TTSButton>
+      )}
+      {isSpeaking && !isPaused && (
+        <TTSButton aria-label="Pause" onClick={onPause}>
+          <Icon.PauseSolid size={iconSize} />
+        </TTSButton>
+      )}
+      {isPaused && (
+        <TTSButton aria-label="Resume" onClick={onResume}>
+          <Icon.ResumeSolid size={iconSize} />
+        </TTSButton>
+      )}
+      <TTSButton aria-label="Stop" onClick={onCancel}>
+        <Icon.StopSolid size={iconSize} />
+      </TTSButton>
+    </UI>
+  )
+}
+
+TextToSpeechControls.displayName = 'TextToSpeechControls'
+TextToSpeechControls.TTSButton = TTSButton
+
+export default TextToSpeechControls

package/src/components/ui.tsx

@@ -0,0 +1,67 @@
+/* eslint-enable react/display-name */
+import React from 'react'
+
+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 FPProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
+  C,
+  {
+    renderStyles?: boolean
+    styles?: React.CSSProperties
+    classes?: string
+    id?: string
+    children?: React.ReactNode
+  }
+>
+
+/*
+ * FPComponent type definition
+ *
+ * Defines the component function signature for the FP component.
+ *
+ * @typeParam C - The HTML element type to render
+ * @param props - The component props
+ * @returns React component
+ */
+type FPComponent = <C extends React.ElementType = 'span'>(
+  props: FPProps<C>,
+) => React.ReactElement | any
+
+const FP: FPComponent = React.forwardRef(
+  <C extends React.ElementType>(
+    { as, styles, classes, children, defaultStyles, ...props }: FPProps<C>,
+    ref?: PolymorphicRef<C>,
+  ) => {
+    const Component = as || 'div'
+
+    const styleObj: React.CSSProperties = { ...defaultStyles, ...styles }
+
+    return (
+      <Component ref={ref} style={styleObj} className={classes} {...props}>
+        {children}
+      </Component>
+    )
+  },
+)
+
+export default FP

package/src/favicon.svg

@@ -0,0 +1,15 @@
+<svg width="410" height="404" viewBox="0 0 410 404" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M399.641 59.5246L215.643 388.545C211.844 395.338 202.084 395.378 198.228 388.618L10.5817 59.5563C6.38087 52.1896 12.6802 43.2665 21.0281 44.7586L205.223 77.6824C206.398 77.8924 207.601 77.8904 208.776 77.6763L389.119 44.8058C397.439 43.2894 403.768 52.1434 399.641 59.5246Z" fill="url(#paint0_linear)"/>
+<path d="M292.965 1.5744L156.801 28.2552C154.563 28.6937 152.906 30.5903 152.771 32.8664L144.395 174.33C144.198 177.662 147.258 180.248 150.51 179.498L188.42 170.749C191.967 169.931 195.172 173.055 194.443 176.622L183.18 231.775C182.422 235.487 185.907 238.661 189.532 237.56L212.947 230.446C216.577 229.344 220.065 232.527 219.297 236.242L201.398 322.875C200.278 328.294 207.486 331.249 210.492 326.603L212.5 323.5L323.454 102.072C325.312 98.3645 322.108 94.137 318.036 94.9228L279.014 102.454C275.347 103.161 272.227 99.746 273.262 96.1583L298.731 7.86689C299.767 4.27314 296.636 0.855181 292.965 1.5744Z" fill="url(#paint1_linear)"/>
+<defs>
+<linearGradient id="paint0_linear" x1="6.00017" y1="32.9999" x2="235" y2="344" gradientUnits="userSpaceOnUse">
+<stop stop-color="#41D1FF"/>
+<stop offset="1" stop-color="#BD34FE"/>
+</linearGradient>
+<linearGradient id="paint1_linear" x1="194.651" y1="8.81818" x2="236.076" y2="292.989" gradientUnits="userSpaceOnUse">
+<stop stop-color="#FFEA83"/>
+<stop offset="0.0833333" stop-color="#FFDD35"/>
+<stop offset="1" stop-color="#FFA800"/>
+</linearGradient>
+</defs>
+</svg>

package/src/hooks/popover/__snapshots__/popover.test.tsx.snap

@@ -0,0 +1,88 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Popover > should show popover on button click 1`] = `
+{
+  "asFragment": [Function],
+  "baseElement": <body>
+    <div>
+      <div
+        data-testid="popover"
+      >
+        <button>
+          Hover here
+        </button>
+        <div
+          style="display: block; position: absolute; background: rgb(0, 0, 0); border: 1px solid #ccc; padding: 10px; color: rgb(255, 255, 255); top: 1px; left: 0px; transition: opacity .5s ease-in-out; opacity: 1; transform: translateY(0px);"
+        >
+          This is a popover.
+        </div>
+      </div>
+    </div>
+  </body>,
+  "container": <div>
+    <div
+      data-testid="popover"
+    >
+      <button>
+        Hover here
+      </button>
+      <div
+        style="display: block; position: absolute; background: rgb(0, 0, 0); border: 1px solid #ccc; padding: 10px; color: rgb(255, 255, 255); top: 1px; left: 0px; transition: opacity .5s ease-in-out; opacity: 1; transform: translateY(0px);"
+      >
+        This is a popover.
+      </div>
+    </div>
+  </div>,
+  "debug": [Function],
+  "findAllByAltText": [Function],
+  "findAllByDisplayValue": [Function],
+  "findAllByLabelText": [Function],
+  "findAllByPlaceholderText": [Function],
+  "findAllByRole": [Function],
+  "findAllByTestId": [Function],
+  "findAllByText": [Function],
+  "findAllByTitle": [Function],
+  "findByAltText": [Function],
+  "findByDisplayValue": [Function],
+  "findByLabelText": [Function],
+  "findByPlaceholderText": [Function],
+  "findByRole": [Function],
+  "findByTestId": [Function],
+  "findByText": [Function],
+  "findByTitle": [Function],
+  "getAllByAltText": [Function],
+  "getAllByDisplayValue": [Function],
+  "getAllByLabelText": [Function],
+  "getAllByPlaceholderText": [Function],
+  "getAllByRole": [Function],
+  "getAllByTestId": [Function],
+  "getAllByText": [Function],
+  "getAllByTitle": [Function],
+  "getByAltText": [Function],
+  "getByDisplayValue": [Function],
+  "getByLabelText": [Function],
+  "getByPlaceholderText": [Function],
+  "getByRole": [Function],
+  "getByTestId": [Function],
+  "getByText": [Function],
+  "getByTitle": [Function],
+  "queryAllByAltText": [Function],
+  "queryAllByDisplayValue": [Function],
+  "queryAllByLabelText": [Function],
+  "queryAllByPlaceholderText": [Function],
+  "queryAllByRole": [Function],
+  "queryAllByTestId": [Function],
+  "queryAllByText": [Function],
+  "queryAllByTitle": [Function],
+  "queryByAltText": [Function],
+  "queryByDisplayValue": [Function],
+  "queryByLabelText": [Function],
+  "queryByPlaceholderText": [Function],
+  "queryByRole": [Function],
+  "queryByTestId": [Function],
+  "queryByText": [Function],
+  "queryByTitle": [Function],
+  "rerender": [Function],
+  "unmount": [Function],
+}
+`;

package/src/hooks/popover/node_modules/.vitest/results.json

@@ -0,0 +1 @@
+{"version":"0.31.1","results":[[":popover.test.tsx",{"duration":0,"failed":true}]]}