{"id":17242620,"url":"https://github.com/robinweser/brandeur","last_synced_at":"2025-04-14T03:25:48.345Z","repository":{"id":218543341,"uuid":"731672332","full_name":"robinweser/brandeur","owner":"robinweser","description":"Convenience tool belt for css-hooks","archived":false,"fork":false,"pushed_at":"2025-03-06T16:51:18.000Z","size":887,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T12:41:07.252Z","etag":null,"topics":["css-hooks","cssinjs","inline-style","styling"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robinweser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"robinweser"}},"created_at":"2023-12-14T15:53:46.000Z","updated_at":"2025-03-06T16:51:21.000Z","dependencies_parsed_at":"2024-01-22T17:58:46.280Z","dependency_job_id":"e82beb0c-ffa9-4d63-a8bf-f864707867a1","html_url":"https://github.com/robinweser/brandeur","commit_stats":null,"previous_names":["robinweser/brandeur"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinweser%2Fbrandeur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinweser%2Fbrandeur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinweser%2Fbrandeur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinweser%2Fbrandeur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robinweser","download_url":"https://codeload.github.com/robinweser/brandeur/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248814625,"owners_count":21165796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css-hooks","cssinjs","inline-style","styling"],"created_at":"2024-10-15T06:13:41.915Z","updated_at":"2025-04-14T03:25:48.316Z","avatar_url":"https://github.com/robinweser.png","language":"JavaScript","funding_links":["https://github.com/sponsors/robinweser"],"categories":[],"sub_categories":[],"readme":"# Brandeur\r\n\r\nBrandeur is a convenience layer and tool belt on top of [css-hooks](https://css-hooks.com) for React.\r\n\r\n\u003cimg alt=\"npm version\" src=\"https://badge.fury.io/js/brandeur.svg\"\u003e \u003cimg alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/brandeur.svg\"\u003e \u003ca href=\"https://bundlephobia.com/result?p=brandeur@latest\"\u003e\u003cimg alt=\"Bundlephobia\" src=\"https://img.shields.io/bundlephobia/minzip/brandeur.svg\"\u003e\u003c/a\u003e\r\n\r\n## Benefits\r\n\r\n- Similar API\r\n- Theming\r\n- RTL Conversion\r\n- Vendor Prefixing\r\n- Fallback Value Support\r\n- Keyframes Support\r\n- Extendable Plugin System\r\n- Fela Plugin Compatibility\r\n- TypeScript Support\r\n\r\n## Installation\r\n\r\n```sh\r\n# npm\r\nnpm i --save brandeur\r\n# yarn\r\nyarn add brandeur\r\n# pnpm\r\npnpm add brandeur\r\n```\r\n\r\n## The Gist\r\n\r\n```javascript\r\nimport { createHooks } from 'brandeur'\r\nimport prefixer, { fallbacks } from 'brandeur-plugin-prefixer'\r\n\r\nconst theme = {\r\n  colors: { primary: 'red' },\r\n}\r\n\r\nconst [staticCSS, css] = createHooks({\r\n  hooks: {\r\n    // either custom hooks or @css-hooks/recommended\r\n  },\r\n  plugins: [prefixer()] as const,\r\n  fallbacks: [\r\n    ...fallbacks,\r\n    { property: 'position', values: ['-webkit-sticky', 'sticky'] },\r\n  ],\r\n  keyframes: {\r\n    fadeIn: {\r\n      from: { opacity: 0 },\r\n      to: { opacity: 1 },\r\n    },\r\n  },\r\n  theme,\r\n})\r\n\r\n// fades in, red color, vendor prefixed and browser-compatible position: sticky\r\nconst style = css(({ theme, keyframes }) =\u003e ({\r\n  animationName: keyframes.fadeIn,\r\n  color: theme.colors.primary,\r\n  position: 'sticky',\r\n  appearance: 'none',\r\n}))\r\n```\r\n\r\n## Why\r\n\r\ntbd.\r\n\r\n## API\r\n\r\nCurrently Brandeur only exposes two functions:\r\n\r\n- [createHooks](#createhooks)\r\n- [fallbackValue](#fallbackValue)\r\n\r\n### createHooks\r\n\r\nThe main API that wraps [createHooks](https://css-hooks.com/docs/react/api) from [css-hooks](https://css-hooks.com).\u003cbr /\u003e\r\nIt returns the same structural array including both the static CSS and the `css` function. The difference is that the static CSS includes more than just the hooks and the `css` function also accepts functions.\r\n\r\n#### Arguments\r\n\r\nIt accepts the following arguments as an object.\r\n\r\n| Argument  | Type               | Description                                                                                                                                                   |\r\n| --------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| plugins   | _Array\\\u003cPlugin\u003e_   | List of plugins that are used to process each style before transforming into a flat hooks style. See [Plugins](#plugins) for a list of all available plugins. |\r\n| fallbacks | _Array\\\u003cFallback\u003e_ | List of fallbacks that are added and automatically replace within style objects.                                                                              |\r\n| keyframes | _Object_           | A map of animationName-keyframe pairs.                                                                                                                        |\r\n| theme     | _Object_           | A theme object that can be accessed from within style functions.                                                                                              |\r\n\r\n##### Plugin\r\n\r\n```ts\r\ntype Plugin = style =\u003e style\r\n```\r\n\r\nPlugins are simple functions that take a style object and return a new one, similar to Fela plugins.\r\n\r\n\u003e **Note**: See [Plugins](#plugins) for a list of all available plugins.\r\n\r\n##### Fallback\r\n\r\n```ts\r\ntype Fallback = {\r\n  property: string | Array\u003cstring\u003e\r\n  values: Array\u003cstring\u003e\r\n  match?: string\r\n}\r\n```\r\n\r\n\u003e **Tip**: The [fallbackValue](#fallbackvalue) API provides a convenient way to create those fallback objects.\r\n\r\n#### Returns\r\n\r\nIt returns an array where the first item is a static CSS string and the second item is the `css` function to create styles. The `css` function accepts both style object as well as functions where the first argument is an object that only has a theme property.\r\n\r\n#### Example\r\n\r\nSee [The Gist](#the-gist).\r\n\r\n### fallbackValue\r\n\r\nA tiny helper function to create fallbacks in a more convenient way.\r\n\r\n#### Arguments\r\n\r\nIt accepts the following arguments as an object.\r\n\r\n| Argument | Type                       | Description                                                                                                     |\r\n| -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |\r\n| property | _Array\\\u003cstring\u003e \\| string_ | A property or list of properties for which the fallback value applies.                                          |\r\n| values   | _Array\\\u003cstring\u003e_           | A list of fallback values where the last one is the default.                                                    |\r\n| match    | _string?_                  | An optional matcher string that's used to replace values in style objects. Defaults to the last `values` value. |\r\n\r\n#### Returns\r\n\r\n(_[Fallback](#fallback)_) An object with respective fallback properties.\r\n\r\n#### Example\r\n\r\n```js\r\nimport { fallbackValue } from 'brandeur'\r\n\r\nconst positionSticky = fallbackValue('position', ['-webkit-sticky', 'sticky'])\r\n```\r\n\r\n## Plugins\r\n\r\nBrandeur becomes really powerful when utilising the rich plugin echosystem. That way, we can extend the styling engine to support our personal needs.\r\n\r\n### Brandeur Plugins\r\n\r\n| Name                                                                                                                           | Description                                                                                                           |\r\n| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |\r\n| [brandeur-plugin-debug](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-debug)                       | Uses [styles-debugger](https://github.com/kitze/styles-debugger) to visually debug styles.                            |\r\n| [brandeur-plugin-enforce-longhand](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-enforce-longhand) | Specific implementation of sort-property. Enforces longhand over shorthand properties for more deterministic results. |\r\n| [brandeur-plugin-prefixer](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-prefixer)                 | Adds vendor prefixes to style objects.                                                                                |\r\n| [brandeur-plugin-sort-property](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-sort-property)       | Sorts properties according to a priorty map. Helpful when trying to enforce certain properties over others.           |\r\n| [brandeur-plugin-responsive-value](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-responsive-value) | Resolves responsive array values.                                                                                     |\r\n\r\n### Fela Plugins\r\n\r\nThanks to similar architecture and API design, brandeur supports almost all [Fela plugins](https://fela.js.org/docs/latest/advanced/plugins) out of the box.\r\n\r\n\u003e **Tip**: In order to get proper types, make sure that you import `brandeur` in the same file where Fela plugins are imported as types for all Fela plugins are shipped with the core package.\r\n\r\n| Name                                                                                                                     | Description                                                                                  | Compatibility                                                                               |\r\n| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\r\n| [fela-plugin-bidi](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-bidi)                             | Enables direction-independent styles by converting them to either `rtl` or `ltr` on the fly. | Does not support context-specific `direction` via `theme`.                                  |\r\n| [fela-plugin-custom-property](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-custom-property)       | Resolves custom properties.                                                                  | Full                                                                                        |\r\n| [fela-plugin-expand-shorthand](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-expand-shorthand)     | Expands shorthand properties into their longhand forms.                                      | Full                                                                                        |\r\n| [fela-plugin-extend](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-extend)                         | Adds a convenient syntax for (conditionally) extending styles.                               | Full                                                                                        |\r\n| [fela-plugin-hover-media](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-hover-media)               | Wraps `:hover` styles in `@media (hover: hover)` queries.                                    | Full                                                                                        |\r\n| [fela-plugin-kebab-case](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-kebab-case)                 | Converts properties written in kebab-case to camelCase.                                      | Full                                                                                        |\r\n| [fela-plugin-logger](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-logger)                         | Logs processed style objects.                                                                | Full                                                                                        |\r\n| [fela-plugin-multiple-selectors](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-multiple-selectors) | Resolves multiple comma-separated selectors to individual object keys.                       | Full                                                                                        |\r\n| [fela-plugin-responsive-value](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-responsive-value)     | Resolves array values to pre-defined media queries. Useful for component APIs.               | Does not support the `props` argument to receive the `theme`. Use a static `theme` instead. |\r\n| [fela-plugin-rtl](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-rtl)                               | Converts styles to their right-to-left counterpart                                           | Does not support context-specific `direction` via `theme`.                                  |\r\n| [fela-plugin-unit](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-unit)                             | Automatically adds units to values if needed.                                                | Full                                                                                        |\r\n| [fela-plugin-validator](https://github.com/robinweser/fela/tree/master/packages/fela-plugin-validator)                   | Validates, logs \u0026 optionally deletes invalid properties for keyframes and rules.             | Full                                                                                        |\r\n\r\n#### Incompatible Plugins\r\n\r\n| Plugin                                                                                                                                                                     | Alternative                                                                                                                 |\r\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\r\n| fela-plugin-prefixer                                                                                                                                                       | Use [brandeur-plugin-prefixer](https://github.com/robinweser/brandeur/tree/main/packages/brandeur-plugin-prefixer) instead. |\r\n| fela-plugin-named-keys\u003cbr/\u003efela-plugin-friendly-pseudo-class\u003cbr/\u003efela-plugin-pseudo-prefixer\u003cbr/\u003efela-plugin-fullscreen-prefixer\u003cbr/\u003efela-plugin-placeholder-prefixer\u003cbr/\u003e | Use `hooks` directly to set those.                                                                                          |\r\n| fela-plugin-embedded                                                                                                                                                       | No replacement yet due to missing font and keyframe primitives.                                                             |\r\n| fela-plugin-theme-value                                                                                                                                                    | No replacement yet due to incompatible plugin APIs.                                                                         |\r\n\r\n## TypeScript\r\n\r\nBrandeur comes with native TypeScript support, but requires some manual setup to get the correct types for all plugins.\r\n\r\n### Style Object\r\n\r\nBy default, Brandeur automatically infers the type just like css-hooks does. It supports all `React.CSSProperties`. For convenience, we also export a `Style` type from brandeur.\r\n\r\nIn order to extend the type with plugins, we need to set them up correctly.\r\n\r\n```tsx\r\nimport { createHooks } from 'brandeur'\r\n\r\nimport extend from 'fela-plugin-extend'\r\nimport responsiveValue, {\r\n  ResponsiveStyle,\r\n} from 'brandeur-plugin-responsive-value'\r\n\r\nconst [staticCSS, css] = createHooks({\r\n  // ... config\r\n  plugins: [\r\n    // allow responsvie array values in extended styles\r\n    extend\u003cResponsiveStyle\u003e(),\r\n    responsiveValue([\r\n      '@media (min-width: 480px)',\r\n      '@media (min-width: 1024px)',\r\n    ]),\r\n    prefixer(),\r\n    // use \"as const\" to get fixed types\r\n  ] as const,\r\n})\r\n```\r\n\r\n### Fela Plugins\r\n\r\nMake sure to import `brandeur` in your configuration file to load all the plugin types for Fela plugins. Otherwise you'll get the native ones from Fela which have conflicting types.\r\n\r\n```tsx\r\n// load types\r\nimport 'brandeur'\r\n\r\nimport extend from 'fela-plugin-extend'\r\nimport hoverMedia from 'fela-plugin-hover-media'\r\n```\r\n\r\n## Keyframes\r\n\r\nBrandeur provides a simple way to create and consume global keyframes. Check [the gist](#the-gist) for an example.\r\n\r\nSometimes however we want to have dynamic keyframes and/or not render all keyframes upfront. In such cases, we recommend using a separate package to deal with that.\u003cbr /\u003e\r\nI created [react-create-keyframe](https://github.com/robinweser/react-create-keyframe) for exactly those use cases. Feel free to check it out!\r\n\r\n## Roadmap\r\n\r\n- Theming Primitives\r\n- Framework-Agnostic API\r\n\r\n## License\r\n\r\nBrandeur is licensed under the [MIT License](http://opensource.org/licenses/MIT).\u003cbr\u003e\r\nDocumentation is licensed under [Creative Commons License](http://creativecommons.org/licenses/by/4.0/).\u003cbr\u003e\r\nCreated with ♥ by [@robinweser](https://weser.io).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinweser%2Fbrandeur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobinweser%2Fbrandeur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinweser%2Fbrandeur/lists"}