<commit_before># Setup

To make use of Aesthetic, we must instantiate an [adapter](./adapters/README.md). The adapter
requires a native library instance as the 1st argument, and an optional Aesthetic options object as
the 2nd argument. Please refer to each adapter for explicit usage.

```ts
import AphroditeAesthetic from 'aesthetic-adapter-aphrodite';

export default new AphroditeAesthetic(extensions, {
  pure: true,
  theme: 'dark',
});
```

The following options are available, most of which can be overridden per component, and all of which
only apply to the `withStyles` API.

- `extendable` (boolean) - Can component styles be extended by other components? Otherwise, the
  styles are locked and isolated. Defaults to `false`.
- `passThemeProp` (boolean) - Should the theme prop be passed to all wrapped components? Defaults to
  `false`.
- `pure` (boolean) - Should all HOC wrapped components use `React.PureComponent`? Defaults to
  `true`.
- `stylesPropName` (string) - The name of the styles prop passed to wrapped components. Defaults to
  `styles`.
- `theme` (string) - The currently active theme. Defaults to `default`.
- `themePropName` (string) - Name of the prop in which to pass the theme object to the wrapped
  component. Defaults to `theme`.

## Creating Helper Functions

All of Aesthetic's functionality, including HOCs and hooks, are utilized through a class instance,
which can be quite cumbersome to use. It's suggested to wrap this functionality in reusable helper
functions.

### useStyles

The `Aesthetic#useStyles` hook can be written as the following.

```ts
// useStyles.ts
import { StyleSheetDefinition } from 'aesthetic';
import aesthetic, { Theme } from './aesthetic';

export default function useStyles<T>(
  styleSheet: StyleSheetDefinition<Theme, T>,
  customName?: string,
) /* infer */ {
  return aesthetic.useStyles(styleSheet, customName);
}
```

### useTheme

The `Aesthetic#useTheme` hook can be written as the following.

```ts
// useTheme.ts
import aesthetic from './aesthetic';

export default function useTheme() /* infer */ {
  return aesthetic.useTheme();
}
```

### withStyles

The `Aesthetic#withStyles` HOC can be written as the following. If using TypeScript, all adapters
export a `ParsedBlock` type that must be passed to the `WithStylesProps` type.

```ts
// withStyles.ts
import {
  StyleSheetDefinition,
  WithStylesOptions,
  WithStylesProps as BaseWithStylesProps,
} from 'aesthetic';
import { ParsedBlock } from 'aesthetic-adapter-aphrodite';
import aesthetic, { Theme } from './aesthetic';

export type WithStylesProps = BaseWithStylesProps<Theme, ParsedBlock>;

export default function withStyles<T>(
  styleSheet: StyleSheetDefinition<Theme, T>,
  options: WithStylesOptions = {},
) /* infer */ {
  return aesthetic.withStyles(styleSheet, options);
}
```

### withTheme

The `Aesthetic#withTheme` HOC can be written as the following.

```ts
// withTheme.ts
import { WithThemeOptions, WithThemeProps as BaseWithThemeProps } from 'aesthetic';
import aesthetic, { Theme } from './aesthetic';

export type WithThemeProps = BaseWithThemeProps<Theme>;

export default function withTheme(options: WithThemeOptions = {}) /* infer */ {
  return aesthetic.withTheme(options);
}
```

### transformStyles

And lastly, the `Aesthetic#transformStyles` method, which is required to transform styles into CSS
class names, can be written as the following. If using TypeScript, the `NativeBlock` and
`ParsedBlock` adapter types must be used for proper type safety.

```ts
// cx.ts
import { NativeBlock, ParsedBlock } from 'aesthetic-adapter-aphrodite';
import aesthetic from './aesthetic';

export default function cx(
  ...styles: (undefined | false | string | NativeBlock | ParsedBlock)[]
): string {
  return aesthetic.transformStyles(...styles);
}
```

> This function is returned as the 2nd value from the `useStyles` hook.

## Bundler Integration

Aesthetic makes heavy use of `process.env.NODE_ENV` for logging errors in development. These errors
will be entirely removed in production if the following build steps are configured.

### Webpack

[EnvironmentPlugin](https://webpack.js.org/plugins/environment-plugin/) plugin is required when
using Webpack.

```ts
new webpack.EnvironmentPlugin(['NODE_ENV']);
```

### Browserify

[Envify](https://github.com/hughsk/envify) transformer is required when using Browserify.

```ts
envify({
  NODE_ENV: process.env.NODE_ENV || 'production',
});
```
<commit_msg>Update API docs.<commit_after># Setup

To make use of Aesthetic, we must instantiate an [adapter](./adapters/README.md). The adapter
requires a native library instance as the 1st argument, and an optional Aesthetic options object as
the 2nd argument. Please refer to each adapter for explicit usage.

```ts
import AphroditeAesthetic from 'aesthetic-adapter-aphrodite';

export default new AphroditeAesthetic(extensions, {
  pure: true,
  theme: 'dark',
});
```

### Options

The following options are available, most of which can be overridden per component when using
`withStyles`.

- `extendable` (boolean) - Can component styles be extended by other components? Otherwise, the
  styles are locked and isolated. Defaults to `false`.
- `passThemeProp` (boolean) - Should the theme prop be passed to all wrapped components? Defaults to
  `false`.
- `pure` (boolean) - Should all HOC wrapped components use `React.PureComponent`? Defaults to
  `true`.
- `stylesPropName` (string) - The name of the styles prop passed to wrapped components. Defaults to
  `styles`.
- `theme` (string) - The currently active theme. Defaults to `default`.
- `themePropName` (string) - Name of the prop in which to pass the theme object to the wrapped
  component. Defaults to `theme`.

## API

All of Aesthetic's functionality, including HOCs and hooks, are utilized through a class instance,
which can be quite cumbersome to use. It's suggested to wrap the following public API methods into
reusable helper functions.

### useStyles

The `Aesthetic#useStyles` hook supports an _optional_ custom component name for use in debugging and
generating class names. This defaults to "Component" if not defined.

```ts
// useStyles.ts
import { StyleSheetDefinition } from 'aesthetic';
import aesthetic, { Theme } from './aesthetic';

export default function useStyles<T>(
  styleSheet: StyleSheetDefinition<Theme, T>,
  componentName?: string,
) /* infer */ {
  return aesthetic.useStyles(styleSheet, componentName);
}
```

### useTheme

The `Aesthetic#useTheme` hook returns the current theme.

```ts
// useTheme.ts
import aesthetic from './aesthetic';

export default function useTheme() /* infer */ {
  return aesthetic.useTheme();
}
```

### withStyles

The `Aesthetic#withStyles` HOC supports all of the [options](#options) mentioned previously, except
for `theme`.

```ts
// withStyles.ts
import {
  StyleSheetDefinition,
  WithStylesOptions,
  WithStylesProps as BaseWithStylesProps,
} from 'aesthetic';
import { ParsedBlock } from 'aesthetic-adapter-aphrodite';
import aesthetic, { Theme } from './aesthetic';

export type WithStylesProps = BaseWithStylesProps<Theme, ParsedBlock>;

export default function withStyles<T>(
  styleSheet: StyleSheetDefinition<Theme, T>,
  options: WithStylesOptions = {},
) /* infer */ {
  return aesthetic.withStyles(styleSheet, options);
}
```

> If using TypeScript, all adapters export a `ParsedBlock` type that must be passed to the
> `WithStylesProps` type.

### withTheme

The `Aesthetic#withTheme` HOC passes the current theme as a prop. It supports the `themePropName`
and `pure` [options](#options) mentioned previously.

```ts
// withTheme.ts
import { WithThemeOptions, WithThemeProps as BaseWithThemeProps } from 'aesthetic';
import aesthetic, { Theme } from './aesthetic';

export type WithThemeProps = BaseWithThemeProps<Theme>;

export default function withTheme(options: WithThemeOptions = {}) /* infer */ {
  return aesthetic.withTheme(options);
}
```

### transformStyles

And lastly, the `Aesthetic#transformStyles` method, which is required to transform styles into CSS
class names. This function is also returned as the 2nd value from the `useStyles` hook.

```ts
// cx.ts
import { NativeBlock, ParsedBlock } from 'aesthetic-adapter-aphrodite';
import aesthetic from './aesthetic';

export default function cx(
  ...styles: (undefined | false | string | NativeBlock | ParsedBlock)[]
): string {
  return aesthetic.transformStyles(...styles);
}
```

> If using TypeScript, the `NativeBlock` and `ParsedBlock` adapter types must be used for proper
> type safety.

## Bundler Integration

Aesthetic makes heavy use of `process.env.NODE_ENV` for logging errors in development. These errors
will be entirely removed in production if the following build steps are configured.

### Webpack

[EnvironmentPlugin](https://webpack.js.org/plugins/environment-plugin/) plugin is required when
using Webpack.

```ts
new webpack.EnvironmentPlugin(['NODE_ENV']);
```

### Browserify

[Envify](https://github.com/hughsk/envify) transformer is required when using Browserify.

```ts
envify({
  NODE_ENV: process.env.NODE_ENV || 'production',
});
```

{'fraction_non_alphanumeric': 0.1052054794520548, 'fraction_numerical': 0.0006575342465753425, 'mean_word_length': 4.861271676300578, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 20, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1246954', 'n_tokens_mistral': 2613, 'n_tokens_neox': 2583, 'n_words': 989}