Merge pull request #1 from phantomstudios/feat/initial-component

Initial version with very minimal tests

Author: John Richard Chipps-Harding

.github/ISSUE_TEMPLATE/REPORT_A_BUG.md

@@ -9,11 +9,11 @@ about: "Is something not working as you expect?"
 
 e.g. "Data refuses to load when accessing via https..."
 
-> Which version of PACKAGE-NAME are you using?
+> Which version of use-local-state are you using?
 
 e.g. `0.1.0`
 
-> What version of React are you using PACKAGE-NAME within?
+> What version of React are you using use-local-state within?
 
 e.g. `16.9.0`
 
@@ -31,8 +31,8 @@ e.g. "The request just hung, no response."
 
 <!--
 Before posting, please check that the bug hasn't already been:
-1. fixed in the next release (https://github.com/phantomstudios/PACKAGE-NAME/blob/master/CHANGELOG.md)
-2. discussed previously (https://github.com/phantomstudios/PACKAGE-NAME/search)
+1. fixed in the next release (https://github.com/phantomstudios/use-local-state/blob/master/CHANGELOG.md)
+2. discussed previously (https://github.com/phantomstudios/use-local-state/search)
 -->
 
 <!--

.github/ISSUE_TEMPLATE/REQUEST_A_FEATURE.md

@@ -15,8 +15,8 @@ e.g. "A new input argument that accepts..."
 
 <!--
 Before posting, please check that the feature hasn't already been:
-1. added in the next release (https://github.com/phantomstudios/PACKAGE-NAME/blob/master/CHANGELOG.md)
-2. discussed previously (https://github.com/phantomstudios/PACKAGE-NAME/search)
+1. added in the next release (https://github.com/phantomstudios/use-local-state/blob/master/CHANGELOG.md)
+2. discussed previously (https://github.com/phantomstudios/use-local-state/search)
 -->
 
 <!--

CONTRIBUTING.md

@@ -4,7 +4,7 @@ I'm really happy that you're interested in helping out with this little project.
 
 As this is very early days for the project there's not a lot in the way of
 resources, but please check out the [documentation](./README.md), and also the
-[list of issues](https://github.com/phantomstudios/PACKAGE-NAME/issues).
+[list of issues](https://github.com/phantomstudios/use-local-state/issues).
 
 Please submit an issue if you need help with anything.
 
@@ -20,7 +20,7 @@ pass. Testing is automated using GitHub Actions CI.
 ## Submitting changes
 
 Please send a
-[GitHub Pull Request to PACKAGE-NAME](https://github.com/phantomstudios/PACKAGE-NAME/pull/new/master)
+[GitHub Pull Request to use-local-state](https://github.com/phantomstudios/use-local-state/pull/new/master)
 with a clear list of what you've done (read more about
 [pull requests](https://help.github.com/en/articles/about-pull-requests)). When you send a pull
 request, please make sure you've covered off all the points in the template.
@@ -43,6 +43,6 @@ In effect this means:
 - Your Pull Request title and description become very important; they are the
   history of the master branch and explain all the changes.
 - You ought to be able to find any previous version easily using GitHub tabs, or
-  [Releases](https://github.com/phantomstudios/PACKAGE-NAME/releases)
+  [Releases](https://github.com/phantomstudios/use-local-state/releases)
 
 Thanks, John Chipps-Harding

README.md

@@ -1,71 +1,80 @@
-# PACKAGE-NAME
+# use-local-state
 
 [![NPM version][npm-image]][npm-url]
 [![Actions Status][ci-image]][ci-url]
 [![PR Welcome][npm-downloads-image]][npm-downloads-url]
 
-Package one-liner overview.
+A simple react hook that allows you to store data within `LocalStorage` with same interface as the standard `React.useState` hook.
 
 ## Introduction
 
-Package introduction, couple of paragraphs.
+Just swap out your `useState` calls with `useLocalState` to persist the data between refreshes. This hook is also SSR safe and does not break when used without `window` existing.
 
 ```javascript
-import useLibrary from "@phntms/PACKAGE-NAME";
+import useLocalState from "@phntms/use-local-state";
 
-const { something } = useLibrary({
-  argument1: "something",
-  argument2: "something else",
-});
+const [token, setToken] = useLocalState("USER_TOKEN", "");
 ```
 
 ## Installation
 
 Install this package with `npm`.
 
 ```bash
-npm i @phntms/PACKAGE-NAME
+npm i @phntms/use-local-state
 ```
 
 ## Usage
 
-Example 1 description.
+Store a boolean to track if a user has detected terms of use.
 
 ```JSX
 import React from 'react';
-import useLibrary from '@phntms/PACKAGE-NAME';
+import useLocalState from '@phntms/use-local-state';
 
 const SomeExample = () = {
-  const { something } = useApi({
-    argument1: "something",
-    argument2: "something else",
-  });
+  const [accepted, setAccepted] = useLocalState("TERMS_ACCEPTED", false);
 
   return (
     <>
-      <h1>Result</h2>
-      <p>{something}</p>
+      <h1>Welcome</h2>
+      {!accepted && <>
+        <p>Do you accept our terms?</p>
+        <button onClick={()=>setAccepted(true)}>Accept</button>
+      </>}
     </>
   );
 }
 ```
 
-Example 2 description.
+Store a list of bookmarks.
 
 ```JSX
 import React from 'react';
-import useLibrary from '@phntms/PACKAGE-NAME';
+import useLocalState from '@phntms/use-local-state';
+
+interface Bookmark {
+  title: string;
+  url: string;
+}
 
 const SomeExample2 = () = {
-  const { something } = useApi({
-    argument1: "something",
-    argument2: "something else",
-  });
+  const [bookmarks, setBookmarks] = useLocalState<Bookmark[]>("BOOKMARKS", []);
+
+  const addBookmark = (bookmark: Bookmark) => setBookmarks([...bookmarks, bookmark]);
+
 
   return (
     <>
-      <h1>Result</h2>
-      <p>{something}</p>
+      <h1>Bookmarks</h2>
+      <NewBookmark add={addBookmark} />
+      <ul>
+        {bookmarks.map(((bookmark, i) => (
+          <li key={i}>
+            <a href={bookmark.url}>{bookmark.title}</a>
+          </li>
+        )))}
+      </ul>
     </>
   );
 }
@@ -75,16 +84,16 @@ const SomeExample2 = () = {
 
 ### Input
 
-- `argument1` : Required - Description of argument.
-- `argument2` : Optional - Description of argument.
+- `key` : Required - The key to store within `LocalStorage`.
+- `initialValue` : Required - The default/initial value if the key is not found within the `LocalStorage` object.
 
 ### Output
 
-- `something`: Description of output.
+An array containing the value and a function to set the value. Signiature is exactly like the standard [React.useState](https://reactjs.org/docs/hooks-state.html) hook.
 
-[npm-image]: https://img.shields.io/npm/v/@phntms/PACKAGE-NAME.svg?style=flat-square&logo=react
-[npm-url]: https://npmjs.org/package/@phntms/PACKAGE-NAME
-[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/PACKAGE-NAME.svg
-[npm-downloads-url]: https://npmcharts.com/compare/@phntms/PACKAGE-NAME?minimal=true
-[ci-image]: https://github.com/phantomstudios/PACKAGE-NAME/workflows/test/badge.svg
-[ci-url]: https://github.com/phantomstudios/PACKAGE-NAME/actions
+[npm-image]: https://img.shields.io/npm/v/@phntms/use-local-state.svg?style=flat-square&logo=react
+[npm-url]: https://npmjs.org/package/@phntms/use-local-state
+[npm-downloads-image]: https://img.shields.io/npm/dm/@phntms/use-local-state.svg
+[npm-downloads-url]: https://npmcharts.com/compare/@phntms/use-local-state?minimal=true
+[ci-image]: https://github.com/phantomstudios/use-local-state/workflows/test/badge.svg
+[ci-url]: https://github.com/phantomstudios/use-local-state/actions

SUPPORT.md

@@ -1,4 +1,4 @@
-# PACKAGE-NAME Support
+# use-local-state Support
 
-For _questions_ on how to use `PACKAGE-NAME` or what went wrong when you tried something, our primary resource is by opening a
-[GitHub Issue](https://github.com/phantomstudios/PACKAGE-NAME/issues), where you can get help from developers.
+For _questions_ on how to use `use-local-state` or what went wrong when you tried something, our primary resource is by opening a
+[GitHub Issue](https://github.com/phantomstudios/use-local-state/issues), where you can get help from developers.

jest.config.js

@@ -2,23 +2,14 @@
  * @type {jest.ProjectConfig}
  */
 module.exports = {
-    roots: [
-      '<rootDir>/test'
-    ],
-    transform: {
-      '^.+\\.tsx?$': 'ts-jest'
+  roots: ["<rootDir>/test"],
+  transform: {
+    "^.+\\.tsx?$": "ts-jest",
+  },
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  globals: {
+    "ts-jest": {
+      tsconfig: "tsconfig.test.json",
     },
-    moduleFileExtensions: [
-      'ts',
-      'tsx',
-      'js',
-      'jsx',
-      'json',
-      'node'
-    ],
-    globals: {
-      'ts-jest': {
-        tsConfig: 'tsconfig.test.json'
-      }
-    }
-  }
+  },
+};

package-lock.json

@@ -1,16 +1,16 @@
 {
-  "name": "@phntms/PACKAGE-NAME",
+  "name": "@phntms/use-local-state",
   "description": "Description, same as overview one-liner from README.md.",
   "version": "0.0.1",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
-  "homepage": "https://github.com/phantomstudios/PACKAGE-NAME#readme",
+  "homepage": "https://github.com/phantomstudios/use-local-state#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/phantomstudios/PACKAGE-NAME.git"
+    "url": "https://github.com/phantomstudios/use-local-state.git"
   },
   "bugs": {
-    "url": "https://github.com/phantomstudios/PACKAGE-NAME/issues"
+    "url": "https://github.com/phantomstudios/use-local-state/issues"
   },
   "keywords": [
     "react",
@@ -67,4 +67,4 @@
     "typescript": "^4.1.5"
   },
   "dependencies": {}
-}
+}

package.json

@@ -1,13 +1,32 @@
-interface Props {
-  argument1: number;
-  argument2?: number;
-}
-
-const useLibrary = ({ argument1, argument2 = 0 }: Props) => {
-  if (!argument1) throw Error("argument 1 not specified");
-  return {
-    something: argument1 + argument2,
+import { useState } from "react";
+
+import { SUPPORTED } from "./utils";
+
+const useLocalState = <T>(
+  key: string,
+  defaultValue: T
+): [T, (v: T | ((v: T) => T)) => void] => {
+  const [value, setValue] = useState<T>(() => {
+    const toStore =
+      typeof defaultValue === "function" ? defaultValue() : defaultValue;
+    if (!SUPPORTED) return toStore;
+    const item = window.localStorage.getItem(key);
+    try {
+      return item ? JSON.parse(item) : toStore;
+    } catch (error) {
+      return toStore;
+    }
+  });
+
+  const setLocalStateValue = (newValue: T | ((v: T) => T)) => {
+    const isCallable = (value: unknown): value is (v: T) => T =>
+      typeof value === "function";
+    const toStore = isCallable(newValue) ? newValue(value) : newValue;
+    if (SUPPORTED) window.localStorage.setItem(key, JSON.stringify(toStore));
+    setValue(toStore);
   };
+
+  return [value, setLocalStateValue];
 };
 
-export default useLibrary;
+export default useLocalState;

src/index.ts

@@ -0,0 +1,3 @@
+export const IS_BROWSER = typeof window !== "undefined";
+
+export const SUPPORTED = IS_BROWSER && window.localStorage;