From 94b1a563f3d9a09af13d0f5e0d0a5f4fd2a7df89 Mon Sep 17 00:00:00 2001 From: Jedrzej Lewandowski Date: Sat, 9 Dec 2017 19:08:17 +0100 Subject: [PATCH] feat: add TS definitions (#11) * feat: add TS definitions * docs: added Typescript Usage md file docs * fix(feat): missing typescript dependency * docs: added contributor, update kcd-scripts --- .all-contributorsrc | 9 ++++++ README.md | 64 +++++++++++++++++++++------------------ other/TYPESCRIPT_USAGE.md | 6 ++++ package.json | 9 ++++-- test/basic.test.tsx | 41 +++++++++++++++++++++++++ tsconfig.json | 7 +++++ typings/index.d.ts | 35 +++++++++++++++++++++ 7 files changed, 139 insertions(+), 32 deletions(-) create mode 100644 other/TYPESCRIPT_USAGE.md create mode 100644 test/basic.test.tsx create mode 100644 tsconfig.json create mode 100644 typings/index.d.ts diff --git a/.all-contributorsrc b/.all-contributorsrc index e75aa19..8871e62 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -38,6 +38,15 @@ "contributions": [ "code" ] + }, + { + "login": "TheFullResolution", + "name": "Jedrzej Lewandowski", + "avatar_url": "https://avatars2.githubusercontent.com/u/11708648?v=4", + "profile": "http://www.thefullresolution.com/", + "contributions": [ + "code" + ] } ] } diff --git a/README.md b/README.md index c7f81ac..277cbab 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ [![Code Coverage][coverage-badge]][coverage] [![downloads][downloads-badge]][npmcharts] [![version][version-badge]][package] -[![MIT License][license-badge]][LICENSE] +[![MIT License][license-badge]][license] -[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors) +[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors) [![PRs Welcome][prs-badge]][prs] [![Chat][chat-badge]][chat] [![Code of Conduct][coc-badge]][coc] @@ -41,18 +41,23 @@ This follows the patterns in [`downshift`][downshift] to expose an API that renders nothing and simply encapsulates the logic of a toggle component. ## Table of Contents + - + -- [Installation](#installation) -- [Usage](#usage) -- [Props:](#props) -- [Examples](#examples) -- [Inspiration](#inspiration) -- [Other Solutions](#other-solutions) -- [Contributors](#contributors) -- [LICENSE](#license) +* [Installation](#installation) +* [Usage](#usage) +* [Props:](#props) + * [defaultOn](#defaulton) + * [onToggle](#ontoggle) + * [on](#on) + * [children](#children) +* [Examples](#examples) +* [Inspiration](#inspiration) +* [Other Solutions](#other-solutions) +* [Contributors](#contributors) +* [LICENSE](#license) @@ -88,7 +93,7 @@ render( )} , - document.getElementById('root') + document.getElementById('root'), ) ``` @@ -110,8 +115,8 @@ The initial `on` state. Called when the toggler is clicked. -- `on`: The new on state -- `TogglerStateAndHelpers`: the exact same thing you get in your child render +* `on`: The new on state +* `TogglerStateAndHelpers`: the exact same thing you get in your child render prop function. ### on @@ -135,12 +140,11 @@ that state from other components, `redux`, `react-router`, or anywhere else. > in react (like ``). If you want to learn more about this concept, you > can learn about that from this the > ["Controlled Components" lecture][controlled-components-lecture] and -> exercises from [React Training's][react-training] -> [Advanced React][advanced-react] course. +> exercises from [React Training's][react-training] > [Advanced React][advanced-react] course. ### children -> `function({})` | *required* +> `function({})` | _required_ This is called with an object. @@ -150,21 +154,21 @@ The function is passed as the child prop: -| property | category | type | description | -|-------------------|-------------|---------------------------|--------------------------------------------------------------------------------------------------| -| `on` | state | `boolean` | The current `on` state of toggle | -| `getTogglerProps` | prop getter | `function(props: object)` | returns the props you should apply to the button element you render. Includes `aria-` attributes | -| `getInputTogglerProps` | prop getter | `function(props: object)` | returns the props you should apply to the input (checkbox) element you render. Includes `aria-` attributes | +| property | category | type | description | +| ------------------------ | ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `on` | state | `boolean` | The current `on` state of toggle | +| `getTogglerProps` | prop getter | `function(props: object)` | returns the props you should apply to the button element you render. Includes `aria-` attributes | +| `getInputTogglerProps` | prop getter | `function(props: object)` | returns the props you should apply to the input (checkbox) element you render. Includes `aria-` attributes | | `getElementTogglerProps` | prop getter | `function(props: object)` | returns the props you should apply to the element you render. Use this if you are not using a button or inputβ€”for example, a span. Includes `aria-` attributes | -| `setOn` | action | `function()` | Sets the `on` state to `true` | -| `setOff` | action | `function()` | Sets the `on` state to `false` | -| `toggle` | action | `function()` | Toggles the `on` state (i.e. if it's currently `true`, will set to `false`) | +| `setOn` | action | `function()` | Sets the `on` state to `true` | +| `setOff` | action | `function()` | Sets the `on` state to `false` | +| `toggle` | action | `function()` | Toggles the `on` state (i.e. if it's currently `true`, will set to `false`) | ## Examples Examples exist on [codesandbox.io][examples]: -- [Bare bones toggle](https://codesandbox.io/s/m38674w9vy) +* [Bare bones toggle](https://codesandbox.io/s/m38674w9vy) If you would like to add an example, follow these steps: @@ -194,8 +198,11 @@ are tons of them, so just Thanks goes to these people ([emoji key][emojis]): -| [
Kent C. Dodds](https://kentcdodds.com)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Code") [πŸ“–](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Documentation") [πŸš‡](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Tests") | [
Frank Tan](https://github.com/tansongyang)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Code") [πŸ“–](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Documentation") [⚠️](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Tests") | [
Oliver](http://www.oliverjam.es)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=oliverjam "Code") | -| :---: | :---: | :---: | + + +| [
Kent C. Dodds](https://kentcdodds.com)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Code") [πŸ“–](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Documentation") [πŸš‡](#infra-kentcdodds "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/kentcdodds/react-toggled/commits?author=kentcdodds "Tests") | [
Frank Tan](https://github.com/tansongyang)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Code") [πŸ“–](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Documentation") [⚠️](https://github.com/kentcdodds/react-toggled/commits?author=tansongyang "Tests") | [
Oliver](http://www.oliverjam.es)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=oliverjam "Code") | [
Jedrzej Lewandowski](http://www.thefullresolution.com/)
[πŸ’»](https://github.com/kentcdodds/react-toggled/commits?author=TheFullResolution "Code") | +| :---: | :---: | :---: | :---: | + This project follows the [all-contributors][all-contributors] specification. @@ -239,7 +246,6 @@ MIT [all-contributors]: https://github.com/kentcdodds/all-contributors [ryan]: https://github.com/ryanflorence [compound-components-lecture]: https://courses.reacttraining.com/courses/advanced-react/lectures/3060560 - [examples]: https://codesandbox.io/search?refinementList%5Btags%5D%5B0%5D=react-toggled%3Aexample&page=1 [controlled-components-lecture]: https://courses.reacttraining.com/courses/advanced-react/lectures/3172720 [react-training]: https://reacttraining.com/ diff --git a/other/TYPESCRIPT_USAGE.md b/other/TYPESCRIPT_USAGE.md new file mode 100644 index 0000000..cf57344 --- /dev/null +++ b/other/TYPESCRIPT_USAGE.md @@ -0,0 +1,6 @@ +# Typescript Usage + +The current bundled Typescript definitions are incomplete and based around the +needs of the developers who contributed them. + +Pull requests to improve them are welcome and appreciated. If you've never contributed to open source before, then you may find [this free video course](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) helpful. diff --git a/package.json b/package.json index 9f3a316..d4e0567 100644 --- a/package.json +++ b/package.json @@ -6,12 +6,14 @@ "main": "dist/react-toggled.cjs.js", "jsnext:main": "dist/react-toggled.esm.js", "module": "dist/react-toggled.esm.js", + "typings": "typings/index.d.ts", "scripts": { "add-contributor": "kcd-scripts contributors add", "build": "kcd-scripts build --bundle --p-react", "lint": "kcd-scripts lint", "test": "kcd-scripts test", "test:cover": "kcd-scripts test --coverage", + "test:ts": "tsc --noEmit -p ./tsconfig.json", "test:update": "npm run test:cover -s -- --updateSnapshot", "test:build": "kcd-scripts test --config other/misc-tests/jest.config.js --no-watch", @@ -19,7 +21,7 @@ "storybook": "start-storybook -p 6006 -c stories", "storybook:build": "cd stories && npm install && cd .. && build-storybook -c stories", - "validate": "kcd-scripts validate lint,build-and-test,test:cover", + "validate": "kcd-scripts validate lint,build-and-test,test:cover,test:ts", "precommit": "kcd-scripts precommit" }, "files": ["dist", "typings", "preact"], @@ -36,13 +38,14 @@ "enzyme-adapter-react-16": "^1.0.1", "enzyme-to-json": "^3.1.2", "jest-serializer-html": "^4.0.0", - "kcd-scripts": "^0.24.0", + "kcd-scripts": "^0.30.4", "preact": "^8.2.1", "preact-render-to-string": "^3.6.3", "prop-types": "^15.5.10", "react": "^16.0.0", "react-dom": "^16.0.0", - "react-test-renderer": "^16.0.0" + "react-test-renderer": "^16.0.0", + "typescript": "^2.6.2" }, "eslintConfig": { "extends": "./node_modules/kcd-scripts/eslint.js" diff --git a/test/basic.test.tsx b/test/basic.test.tsx new file mode 100644 index 0000000..ff697ea --- /dev/null +++ b/test/basic.test.tsx @@ -0,0 +1,41 @@ +import * as React from 'react' +import Toggle from '../' + +interface Props {} + +interface State {} + +export default class App extends React.Component { + + onClickCall = () => console.log('hello') + + render() { + return ( + + {({ + on, + getTogglerProps, + toggle, + setOn, + setOff, + getInputTogglerProps, + getElementTogglerProps + }) => ( +
+ + + + + + ToggleSpan +
{on ? 'Toggled On' : 'Toggled Off'}
+
+ )} + + ) + } +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..98cf656 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,7 @@ +{ + "compilerOptions": { + "jsx": "react", + "noUnusedLocals": true + }, + "include": ["test/**/*.tsx"] +} diff --git a/typings/index.d.ts b/typings/index.d.ts new file mode 100644 index 0000000..9000a7a --- /dev/null +++ b/typings/index.d.ts @@ -0,0 +1,35 @@ +import * as React from 'react' + +export interface GetElementPropsOptions extends React.HTMLProps {} + +export interface GetInputPropsOptions + extends React.HTMLProps {} + +export interface GetButtonPropsOptions + extends React.HTMLProps {} + +export interface TogglerStateAndHelpers { + readonly on: boolean + readonly getTogglerProps: (options?: GetButtonPropsOptions) => any + readonly getInputTogglerProps: (options?: GetButtonPropsOptions) => any + readonly getElementTogglerProps: (options?: GetElementPropsOptions) => any + readonly setOn: () => void + readonly setOff: () => void + readonly toggle: () => void +} + +export type ChildrenFunction = ( + options: TogglerStateAndHelpers, +) => React.ReactNode + +export interface ReactToggledProps { + readonly defaultOn?: boolean + readonly onToggle?: (on: boolean, object: TogglerStateAndHelpers) => void + readonly on?: boolean + readonly children: ChildrenFunction +} + +export type ReactToggledInterface = React.ComponentClass + +declare const Toggle: ReactToggledInterface +export default Toggle