open-index/open-npm huggingface dataset:
npm package: @stack-spot/portal-observability
Description: Implements the general observability for a Stackspot web application.
Latest version: 0.8.3

# Observability

Implements the general observability for a Stackspot web application.

## Datadog

### `datadogInit({ applicationId, clientToken, env, service })`

Use this function when you want to init Datadog. Usually we use this function on `App.tsx`.

> **If you are using Portal MFE**. You don't need to use this.

### `useDatadogSetUser()`

Use this function when you want to set user on Datadog. Usually we use this function on `main.tsx`.

> **If you are using Portal MFE**. You don't need to use this.

### `trackError(error: unknown, context?: object | undefined)`

Use this function when you want to set errors on Datadog.

```typescript
import { trackError } from '@stack-spot/portal-observability'

<RawLayout
  header={<Header />}
  menuSections={<SectionMenu />}
  menuContent={<ContentMenu />}
  onError={(error) => trackError(error, { scope: 'error-boundary' })}
>
  {content}
</RawLayout>
```

### `trackPageLoaded(routeDetails: EventPageDetails)`

Use this function when you want to track pages on Datadog.

```typescript
export interface EventPageDetails {
  pathNameWithParams: string,
  searchParamsWithVariableName?: string,
  searchParams?: string,
  routeParams?: Record<string, string | string[] | undefined>,
}
```

### `getRouteForAnalytics({ route, params }: { route: Record<string, any>, params: Record<string, any> })`

This function generates information to about route, usually we use this information combined with `trackPageLoaded` function.

```typescript
import { useRouteData } from 'navigation'
import { getRouteForAnalytics, trackPageLoaded } from '@stack-spot/portal-observability'

const routeInfo = useRouteData()

useEffect(() => {
    const routeForAnalytics = getRouteForAnalytics(routeInfo)
    trackPageLoaded(routeForAnalytics)
  }, [routeInfo.route.$path, routeInfo.params])
```
npm package: @stack-spot/portal-theme
Description: This library contains the StackSpot theme (css) and many utilities to use and manipulate it.
Latest version: 1.3.1

# Theme
This library contains the StackSpot theme (css) and many utilities to use and manipulate it.

Attention: this is not Citric, our design system (DS), instead, it's a configuration that we pass to it.

Platforms: this library is compatible with the web (browser) and VSCode (used by the StackSpot AI extension).

## Incomplete set of tokens
This library is mostly dealing with colors. The rest of the theme is still defined by Citric. This will be reviewed in a future version, along with Citric itself.

## Using the theme

1. Import the css into your main project file:
```ts
import '@stack-spot/portal-theme/dist/theme.css'
```
2. Setup the theme provider for Citric.
```tsx
import { CSSToCitricAdapter } '@stack-spot/portal-theme'

const App = () => (
  <CSSToCitricAdapter>
    // Your content goes here. Every component of Citric will be aware of the theme from this point on.
  </CSSToCitricAdapter>
)
```
3. You can now use the theme in your jsx to define colors:
```tsx
<p style={{ color: theme.color.primary['500'] }}>Hello World!</p>
```
4. You can also use the css variables defined by the theme in your css files:
```css
.my-class {
  background-color: var(--light-400);
}
```

## Reading and changing the current theme
- `getThemeName()`: gets the current theme name.
- `getThemeKind()`: returns "dark" if the theme is mostly dark or "light" if the theme is mostly light. This can be different than the theme name.
- `useThemeName()`: a React Hook to get the current theme name. Use this if you need your content to update when the theme changes.
- `useThemeKind()`: a React Hook to get the current theme kind. Use this if you need your content to update when the theme changes.
- `loadTheme()`: loads the theme from the cookie "theme".
- `setTheme(themeName)`: changes the current theme.

Observations:
- The default theme is "dark".
- The theme is always defined by the attributes `data-theme-name` and `data-theme-kind` on the tag `body`.
- The theme automatically updates across multiple windows.

## Utilities
- `withOpacity(variableName)`: applies an opacity to a theme css color variable.
- `contrastColor(color, level)`: gets the ideal contrast color for the color passed as parameter.
- `createColorSequence(options)`: generates a pre-defined, cyclic, set of ideally spread colors from the theme palette.
- `paletteSequence(options)`: same as `createColorSequence`, but generates the css variable instead.
- `valueOf(variableName)`: gets the value of a CSS variable.
- `listToClass(classList)`: removes all falsy values from the array and joins every item into a valid class string.
npm package: @stack-spot/portal-translate
Description: This is a very simple library common to every StackSpot Web project. This is responsible for implementing internationalization and, by default, supports english and portuguese.
Latest version: 2.2.1

# Translate

This is a very simple library common to every StackSpot Web project. This is responsible for implementing internationalization and, by
default, supports english and portuguese.

## Main functionalities

1. Get the current language: `getLanguage`, `useLanguage`.
2. Change the current language: `setLanguage`.
3. Get the translations from a dictionary according to the current language: `translate`, `useTranslate`.
4. Interpolate a string with variables: `interpolate`.

## Example on React
```tsx
import { useTranslate, interpolate, Dictionary } from '@stack-spot/portal-translate'

const MyComponent = ({ username }: { username: string }) => {
  const t = useTranslate(dictionary)
  const language = useLanguage()

  return (
    <>
      <h1>{t.title}</h1>
      <p>{interpolate(t.hello, username, new Date().toLocaleString(language))}</p>
    </>
  )
}

const dictionary = {
  en: {
    title: 'Main page',
    hello: 'Hello $0, today it is $1.',
  },
  pt: {
    title: 'Página principal',
    hello: 'Olá $0, hoje é $1.',
  },
} satisfies Dictionary
```

## Multiple language support
To change the language configuration, one can call `setupTranslation` and specify a new default language and a new list of supported
languages.

To just add a new language on top of 'pt' and 'en', call `addLanguageSupport($language)` as soon as possible in your application.

For declaring Dictionaries with languages other than portuguese and english, specify all languages in a generic:

```ts
const dictionary = {
  es: {
    hello: 'Hola',
  },
  fr: {
    hello: 'Salut',
  },
} satisfies Dictionary<'es' | 'fr'>
```

`ESDict` is a useful type alias for `Dictionary<'pt' | 'es' | 'en'>`:

```ts
const dictionary = {
  es: {
    hello: 'Hola',
  },
  pt: {
    hello: 'Olá',
  },
  en: {
    hello: 'Hello',
  }
} satisfies ESDict
```

If a dictionary doesn't contain the translations for the current language, the default language is used (english by default). To change the
default language, call `setupTranslation`.

When using multi-language support, instead of hardcoding the supported languages, you can use `getSupportedLanguages()` and
`useSupportedLanguages()` to list all languages that are currently supported.