npm - @koine/react - Versions diffs - 2.0.0-beta.132 → 2.0.0-beta.133 - Mend

@koine/react 2.0.0-beta.132 → 2.0.0-beta.133

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/FaviconTags.d.ts +10 -0
package/Meta.d.ts +10 -0
package/Polymorphic.d.ts +13 -0
package/calendar/calendar-api-google.d.ts +8 -0
package/calendar/types.d.ts +19 -0
package/calendar/useCalendar.d.ts +14 -0
package/calendar/useDateLocale.d.ts +6 -0
package/classed.d.ts +19 -0
package/createUseMediaQueryWidth.d.ts +6 -0
package/extendComponent.d.ts +11 -0
package/forms/antispam.d.ts +20 -0
package/package.json +3 -3
package/useAsyncFn.d.ts +3 -0
package/useFirstMountState.d.ts +3 -0
package/useFixedOffset.d.ts +9 -0
package/useFocus.d.ts +3 -0
package/useInterval.d.ts +5 -0
package/useIsomorphicLayoutEffect.d.ts +3 -0
package/useMeasure.d.ts +5 -0
package/useMountedState.d.ts +3 -0
package/useNavigateAway.d.ts +29 -0
package/usePrevious.d.ts +3 -0
package/useReveal.d.ts +21 -0
package/useScrollPosition.d.ts +7 -0
package/useSmoothScroll.d.ts +6 -0
package/useSpinDelay.d.ts +12 -0
package/useTraceUpdate.d.ts +3 -0
package/useUpdateEffect.d.ts +3 -0
package/useWindowSize.d.ts +9 -0

package/FaviconTags.d.ts CHANGED Viewed

@@ -5,5 +5,15 @@ export type FaviconTagsProps = {
     tileColor?: string;
     themeColor?: string;
 };
+/**
+ * Favicon tags.
+ *
+ * This component is meant to be wrapped in a `<head>` manager component.
+ *
+ * These tags have been produced by [realfavicongenerator.net](https://realfavicongenerator.net/)
+ * on _**16 Feb 2022**_.
+ *
+ * @see https://realfavicongenerator.net/
+ */
 export declare let FaviconTags: ({ name, color, safariTabColor, tileColor, themeColor, }: FaviconTagsProps) => import("react/jsx-runtime").JSX.Element;
 export default FaviconTags;

package/Meta.d.ts CHANGED Viewed

@@ -1,4 +1,14 @@
 export type MetaProps = {
+    /**
+     * Determines whether `user-scalable=0` is add to the `meta->viewport` content
+     *
+     * This is an opt in instead of the default browser behaviour as it helps prevent
+     * weird zooming on input fields on iPhone iOS devices.
+     * @see https://www.warrenchandler.com/2019/04/02/stop-iphones-from-zooming-in-on-form-fields/
+     * @see https://css-tricks.com/16px-or-larger-text-prevents-ios-form-zoom/
+     *
+     * @default false
+     */
     zoom?: boolean;
 };
 export declare let Meta: ({ zoom }: MetaProps) => import("react/jsx-runtime").JSX.Element;

package/Polymorphic.d.ts CHANGED Viewed

@@ -1,3 +1,16 @@
+/**
+ * React Polymorphic components type utilities
+ *
+ * @resources
+ * - [Polymorphic types from Radix UI in Wanda System](https://github.com/wonderflow-bv/wanda/blob/main/packages/react-components/src/types/polymorphic/index.ts)
+ * - [TypeScript + React: Typing Generic forwardRefs](https://fettblog.eu/typescript-react-generic-forward-refs/)
+ * - [React with Typescript -- Generics while using React.forwardRef](https://stackoverflow.com/a/58473012/1938970)
+ * - [How to write a generic that extracts the prop types of the component that passed in](https://stackoverflow.com/a/57846897/1938970)
+ * - [React TS Generic component to pass generic props to children](https://stackoverflow.com/a/68442669/1938970)
+ * - [About custom ref prop](https://gist.github.com/gaearon/1a018a023347fe1c2476073330cc5509)
+ * - [forwardRef performance](https://github.com/facebook/react/issues/13456)
+ * - [React docs: Exposing DOM Refs to Parent Components](https://github.com/facebook/react/issues/13456)
+ */
 export declare namespace Polymorphic {
     type Merge<P1 = Record<string, never>, P2 = Record<string, never>> = Omit<P1, keyof P2> & P2;
     type ComponentTypes = React.ComponentClass<any> | React.FunctionComponent<any> | keyof JSX.IntrinsicElements;

package/calendar/calendar-api-google.d.ts CHANGED Viewed

@@ -1,9 +1,17 @@
 import type { CalendarEventsMap, Calendars } from "./types";
 type GetCalendarsEventsFromGoogleOptions = {
+    /** Fall back to `process.env.GOOGLE_CALENDAR_API_KEY */
     apiKey?: string;
+    /** Start gethering events from date */
     start: Date;
+    /** End gethering events at date */
     end: Date;
+    /**
+     * The default is the time zone of the calendar
+     * @see https://developers.google.com/calendar/api/v3/reference/events/list
+     */
     timeZone?: string;
+    /** The calendars settings */
     calendars: Calendars;
 };
 export declare let getCalendarsEventsFromGoogle: ({ calendars, ...options }: GetCalendarsEventsFromGoogleOptions) => Promise<CalendarEventsMap>;

package/calendar/types.d.ts CHANGED Viewed

@@ -1,6 +1,10 @@
 export type Calendar = {
     id: string;
     color: string;
+    /**
+     * If not defined the name is gathered from the remote calendar response,
+     * for google calendars that comes from the `summary` value.
+     */
     name?: string;
 };
 export type Calendars = Calendar[];
@@ -12,8 +16,17 @@ export type CalendarRange = [Date, Date];
 export type CalendarView = "month" | "week";
 export type CalendarEvent = {
     calendar: Calendar;
+    /**
+     * List of day timestamps across which the event spans
+     */
     days: number[];
+    /**
+     * Lookup object for day timestamps across which the event spans
+     */
     daysMap: Record<number, 1>;
+    /**
+     * Flag for events that spans across multiple days
+     */
     multi: boolean;
     allDay: boolean;
     link: string;
@@ -27,7 +40,13 @@ export type CalendarEvent = {
     description: string;
     uid: string;
 };
+/**
+ * Calendar events mapped by day `timestamp` number
+ */
 export type CalendarEventsByTimestamp = Record<number, CalendarEventsMap>;
+/**
+ * Calendar events map by `uid`
+ */
 export type CalendarEventsMap = Record<CalendarEvent["uid"], CalendarEvent>;
 export type CalendarViewWeeks = CalendarViewWeek[];
 export type CalendarViewWeek = {

package/calendar/useCalendar.d.ts CHANGED Viewed

@@ -3,13 +3,27 @@ import type { KoineCalendarDaygridTableProps } from "./CalendarDaygridTable";
 import type { KoineCalendarLegendProps } from "./CalendarLegend";
 import type { CalendarEvent, CalendarEventsMap, CalendarView, Calendars } from "./types";
 export type UseCalendarProps = {
+    /** The locale to format with `date-fns` */
     locale: string;
+    /** Calendars infos to use */
     calendars: Calendars;
+    /** Fall back to `process.env.GOOGLE_CALENDAR_API_KEY */
     apiKey?: string;
+    /** The key is the event `uid` */
     events?: CalendarEventsMap;
+    /** It defaults to the first of the current month */
     start?: Date;
+    /** It defaults to the last day of the current month */
     end?: Date;
+    /**
+     * The calendar view
+     * @default "month"
+     */
     view?: CalendarView;
+    /**
+     * The default is the time zone of the calendar
+     * @see https://developers.google.com/calendar/api/v3/reference/events/list
+     */
     timeZone?: string;
     onError?: (e: any) => void;
 };

package/calendar/useDateLocale.d.ts CHANGED Viewed

@@ -1,2 +1,8 @@
 import type { Locale } from "date-fns";
+/**
+ * Dynamically import the date-fns correct locale
+ *
+ * Inspired by:
+ * @see https://robertmarshall.dev/blog/dynamically-import-datefns-locale-mui-datepicker-localization/
+ */
 export declare let useDateLocale: (locale?: string, defaultLocale?: string) => Locale | undefined;

package/classed.d.ts CHANGED Viewed

@@ -4,5 +4,24 @@ type ClassedAugmentedProps<Props> = Props & {
     ref?: React.Ref<any>;
 };
 type ClassedFinalProps<Props, Component> = Component extends React.ReactHTML ? React.HTMLProps<Component> & ClassedAugmentedProps<Props> : ClassedAugmentedProps<Props>;
+/**
+ * This utility allows to extend a component a là `styled-components` but for
+ * a className based styling solution like Tailwind,
+ *
+ * It also plays nicely with tailwind intellisense:
+ * - https://github.com/tailwindlabs/tailwindcss-intellisense#tailwindcssclassattributes
+ *
+ * For references about tagged functions:
+ * - https://javascript.plainenglish.io/how-css-in-js-libraries-work-da4145b1b6c7
+ * - https://makersden.io/blog/reverse-engineering-styled-components
+ * - https://typesafe.blog/article/the-logic-behind-javascript-tag-functions
+ * - https://flaming.codes/posts/typescript-and-javascript-tagged-template-strings
+ *
+ * Similar projects:
+ * - https://reactjsexample.com/style-radix-ui-components-with-tailwindcss/
+ *
+ * Discussions and Q/A:
+ * - https://stackoverflow.com/q/73055695/1938970
+ */
 export declare let classed: <Props, Component extends React.ElementType = any>(component: Component) => (strings: TemplateStringsArray, ...args: ((props: Props) => string)[] | string[]) => React.ForwardRefExoticComponent<React.PropsWithoutRef<ClassedFinalProps<Props, Component>> & React.RefAttributes<Component>>;
 export default classed;

package/createUseMediaQueryWidth.d.ts CHANGED Viewed

@@ -2,5 +2,11 @@ import { type GetMediaQueryWidthResolversBreakpoints } from "@koine/utils";
 type _MediaQuerWidthDefExplicit<TBreakpoint extends string> = `min-${TBreakpoint}` | `max-${TBreakpoint}` | `up-${TBreakpoint}` | `down-${TBreakpoint}` | `between-${TBreakpoint}_${TBreakpoint}` | `only-${TBreakpoint}`;
 export type MediaQuerWidthDef<TBreakpoint extends string> = `${TBreakpoint}` | _MediaQuerWidthDefExplicit<TBreakpoint>;
 export type MediaQueryWidth<TBreakpoint extends string> = `@${MediaQuerWidthDef<TBreakpoint>}`;
+/**
+ * Use `null` instead of `false` as default value, @see https://observablehq.com/@werehamster/avoiding-hydration-mismatch-when-using-react-hooks
+ *
+ * @param customBreakpoints
+ * @returns
+ */
 export declare let createUseMediaQueryWidth: <TBreakpointsConfig extends GetMediaQueryWidthResolversBreakpoints>(customBreakpoints: TBreakpointsConfig) => <TBreakpoints extends Extract<keyof TBreakpointsConfig, string>>(media: MediaQueryWidth<TBreakpoints>, serverValue?: null | boolean) => boolean | null;
 export default createUseMediaQueryWidth;

package/extendComponent.d.ts CHANGED Viewed

@@ -9,6 +9,17 @@ export interface OverridableComponents {
         motionable?: boolean;
     };
 }
+/**
+ * Type to define a component that has overridable components.
+ *
+ * Each of them can define its:
+ * - `type`: either as a native HTMLElement (the props for that element will be
+ * automatically inferred) or as a custom React component
+ * - `props`: any additional custom props
+ * - `motionable`: if that component has a possible implementation with `framer-motion`,
+ * in that case we remove some HTMLAttributes props which collides with
+ * `MotionProps` from framer.
+ */
 export type WithComponents<Props, Components extends OverridableComponents> = Props & {
     [Name in keyof Components]: NonNullable<Components[Name]["type"] extends keyof JSX.IntrinsicElements ? React.ElementType<Components[Name]["motionable"] extends true ? Omit<React.ComponentPropsWithoutRef<Components[Name]["type"]>, HtmlAttributesCollidingWithMotionProps> & Components[Name]["props"] : React.ComponentPropsWithoutRef<Components[Name]["type"]> & Components[Name]["props"]> : Components[Name]["type"]>;
 };

package/forms/antispam.d.ts CHANGED Viewed

@@ -1,4 +1,15 @@
 import { type ObjectShape } from "@kuus/yup";
+/**
+ * Encode form
+ *
+ * Takes a record of yup validations and outputs a `yup` schema with encoded
+ * names (antispam technique) and a record of the encoded/decoded input `name`s.
+ *
+ * We skip the names prefixed wth an underscore which are considered programmatic
+ * form data not created by user input.
+ *
+ * FIXME: types https://github.com/jquense/yup/issues/1700
+ */
 export declare let encodeForm: <T extends ObjectShape = {}>(validationRules: T) => {
     encodedSchema: import("@kuus/yup").ObjectSchema<{
         [x: string]: T[keyof T] extends import("@kuus/yup").ISchema<any, any, any, any> ? T[keyof T]["__outputType"] : T[keyof T] extends {
@@ -24,4 +35,13 @@ export declare let encodeForm: <T extends ObjectShape = {}>(validationRules: T)
     }, "">;
     encodedNames: Record<keyof T, string>;
 };
+/**
+ * Decode form data
+ *
+ * This function is meant to be used inside an api endpoint to gather an encoded
+ * form submit data and transform it to the decoded desired json data.
+ *
+ * Here too we skip encoding/decoding process for names prefixed wth an underscore
+ * which are considered programmatic form data not created by user input.
+ */
 export declare let decodeForm: <ReturnAs extends Record<string, unknown> = {}, FormData extends Record<string, unknown> = {}>(formData: FormData) => ReturnAs;

package/package.json CHANGED Viewed

@@ -2,8 +2,8 @@
   "name": "@koine/react",
   "sideEffects": false,
   "dependencies": {
-    "@koine/dom": "2.0.0-beta.132",
-    "@koine/utils": "2.0.0-beta.132"
+    "@koine/dom": "2.0.0-beta.133",
+    "@koine/utils": "2.0.0-beta.133"
   },
   "peerDependencies": {
     "@kuus/yup": "1.0.0-beta.7",
@@ -223,5 +223,5 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.esm.d.ts",
-  "version": "2.0.0-beta.132"
+  "version": "2.0.0-beta.133"
 }

package/useAsyncFn.d.ts CHANGED Viewed

@@ -20,5 +20,8 @@ export type UseAsyncState<T> = {
 };
 type StateFromFunctionReturningPromise<T extends FunctionReturningPromise> = UseAsyncState<PromiseType<ReturnType<T>>>;
 export type UseAsyncFnReturn<T extends FunctionReturningPromise = FunctionReturningPromise> = [StateFromFunctionReturningPromise<T>, T];
+/**
+ * @borrows [streamich/react-use](https://github.com/streamich/react-use/blob/master/src/useAsyncFn.ts)
+ */
 export declare let useAsyncFn: <T extends FunctionReturningPromise>(fn: T, deps?: React.DependencyList, initialState?: StateFromFunctionReturningPromise<T>) => UseAsyncFnReturn<T>;
 export default useAsyncFn;

package/useFirstMountState.d.ts CHANGED Viewed

@@ -1,2 +1,5 @@
+/**
+ * @borrows [streamich/react-use](https://github.com/streamich/react-use/blob/master/src/useFirstMountState.ts)
+ */
 export declare let useFirstMountState: () => boolean;
 export default useFirstMountState;

package/useFixedOffset.d.ts CHANGED Viewed

@@ -1,2 +1,11 @@
+/**
+ * # Use fixed offset
+ *
+ * Maybe use [ResizeObserver polyfill](https://github.com/juggle/resize-observer)
+ *
+ * @see https://web.dev/resize-observer/
+ *
+ * @param selector By default `[data-fixed]`: anyhting with the data attribute `data-fixed`
+ */
 export declare let useFixedOffset: (selector?: string) => import("react").MutableRefObject<number>;
 export default useFixedOffset;

package/useFocus.d.ts CHANGED Viewed

@@ -1,2 +1,5 @@
+/**
+ * @see https://stackoverflow.com/a/54159564/1938970
+ */
 export declare let useFocus: () => (import("react").RefObject<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement> | (() => void))[];
 export default useFocus;

package/useInterval.d.ts CHANGED Viewed

@@ -1,2 +1,7 @@
+/**
+ * @borrows [dan abramov](https://overreacted.io/making-setinterval-declarative-with-react-hooks/)
+ *
+ * We just add `deps` array argument and typescript support
+ */
 export declare let useInterval: <T extends () => unknown>(callback: T, delay: number, deps?: unknown[]) => void;
 export default useInterval;

package/useIsomorphicLayoutEffect.d.ts CHANGED Viewed

@@ -1,3 +1,6 @@
 import { useLayoutEffect } from "react";
+/**
+ * @borrows [streamich/react-use](https://github.com/streamich/react-use/blob/master/src/useIsomorphicLayoutEffect.ts)
+ */
 export declare let useIsomorphicLayoutEffect: typeof useLayoutEffect;
 export default useIsomorphicLayoutEffect;

package/useMeasure.d.ts CHANGED Viewed

@@ -18,5 +18,10 @@ export type UseMeasureReturn = [
     RectReadOnly,
     () => void
 ];
+/**
+ * Use measure hook
+ *
+ * @borrows [pmndrs/react-use-measure](https://github.com/pmndrs/react-use-measure)
+ */
 export declare let useMeasure: (options?: UseMeasureOptions) => UseMeasureReturn;
 export default useMeasure;

package/useMountedState.d.ts CHANGED Viewed

@@ -1,2 +1,5 @@
+/**
+ * @borrows [streamich/react-use](https://github.com/streamich/react-use/blob/master/src/useMountedState.ts)
+ */
 export declare let useMountedState: () => (() => boolean);
 export default useMountedState;

package/useNavigateAway.d.ts CHANGED Viewed

@@ -1,3 +1,32 @@
+/**
+ * @return A custom error message (most browser will ignore it), or just a
+ * boolean to signal whether we want to prompt the user
+ *
+ * We might instead return an array with the above as first element and two
+ * callbacks, but the callback technique is too cumbersome and unreliable
+ * probably:
+ * 2) A callback on confirmed leaving
+ * 3) A callback on cancel, user stays on page
+ */
 export type UseNavigateAwayHandler = (event: BeforeUnloadEvent) => string | boolean;
+/**
+ * @resources
+ *
+ * About browser's specs see:
+ * - https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
+ * - https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/HandlingEvents/HandlingEvents.html#//apple_ref/doc/uid/TP40006511-SW5
+ * - https://stackoverflow.com/questions/58009424/pagehide-event-on-google-chrome
+ *
+ * About react see:
+ * - https://github.com/jacobbuck/react-beforeunload
+ * - https://github.com/dioscarey/react-beforeunload-component
+ *
+ * About next.js see:
+ * - https://github.com/vercel/next.js/issues/2476
+ * - https://github.com/vercel/next.js/issues/2694
+ *
+ * For the callback technique see:
+ * - https://stackoverflow.com/a/11835394/1938970
+ */
 export declare let useNavigateAway: (handler: UseNavigateAwayHandler) => void;
 export default useNavigateAway;

package/usePrevious.d.ts CHANGED Viewed

@@ -1,2 +1,5 @@
+/**
+ * @borrows [samselikoff/animated-carousel](https://github.com/samselikoff/2022-06-02-animated-carousel/blob/main/pages/final.jsx)
+ */
 export declare let usePrevious: <T extends unknown>(state: T, defaulValue: T) => T;
 export default usePrevious;

package/useReveal.d.ts CHANGED Viewed

@@ -1,7 +1,28 @@
 export type UseRevealOptions = {
+    /**
+     * @default "left"
+     */
     direction?: "left" | "right";
+    /**
+     * A number that represents the offset to start the animations, giving `-1`
+     * means that the animation will start when the scroll position is at
+     * 100% higher than the given element. Giving `2` the animation will starts
+     * when the scroll reached two times the height of the given element below
+     * the top edge of the element itself
+     *
+     * @default -2
+     */
     offsetStartY?: number;
+    /**
+     * When 0 it defaults to the same as the offsetStartY
+     * @default 0
+     */
     offsetEndY?: number;
+    /**
+     * A value from `0` to `1` representing a proportion of the element width
+     * or "all" to make it completely out of the viewport
+     * @default "all"
+     * */
     offsetStartX?: number | "all";
 };
 export declare let useReveal: <T extends HTMLElement = HTMLDivElement>({ direction, offsetStartY, offsetEndY, offsetStartX, }: UseRevealOptions) => {

package/useScrollPosition.d.ts CHANGED Viewed

@@ -3,5 +3,12 @@ type Position = {
     y: number;
 };
 type ElementRef = React.MutableRefObject<HTMLElement | undefined>;
+/**
+ * @borrows [@n8tb1t/use-scroll-position@2.0.3](https://github.com/n8tb1t/use-scroll-position) by `n8tb1t <n8tb1t@gmail.com>`
+ *
+ * We've just:
+ * - reused internal helper functions
+ * - compacted object arguments in functions as plain argument list to improve compression
+ */
 export declare let useScrollPosition: (effect: (currentPosition: Position, prevPosition: Position) => void, deps?: React.DependencyList, element?: ElementRef, boundingElement?: ElementRef, wait?: number) => void;
 export default useScrollPosition;

package/useSmoothScroll.d.ts CHANGED Viewed

@@ -1,2 +1,8 @@
+/**
+ *
+ * @param disregardAutomaticFixedOffset When the `to` scroll argument is a DOM
+ * selector we will keep into account the _fixedOffset_ despite this option.
+ * @returns
+ */
 export declare let useSmoothScroll: (disregardAutomaticFixedOffset?: boolean) => (to?: number | string, customOffset?: number, callback?: () => void, fallbackTimeout?: number, behavior?: ScrollBehavior) => void;
 export default useSmoothScroll;

package/useSpinDelay.d.ts CHANGED Viewed

@@ -1,2 +1,14 @@
+/**
+ * Wraps your booleans only returning true after the `delay`, and for a minimum
+ * time of `minDuration`. This way you're sure that you don't show unnecessary
+ * or very short living spinners.
+ *
+ * @borrows [smeijer/spin-delay](https://github.com/smeijer/spin-delay)
+ *
+ * - Smaller footprint and options object as argument
+ *
+ * @param delay [500]
+ * @param minDuration [200]
+ */
 export declare let useSpinDelay: (loading: boolean, delay?: number, minDuration?: number) => boolean;
 export default useSpinDelay;

package/useTraceUpdate.d.ts CHANGED Viewed

@@ -1,2 +1,5 @@
+/**
+ * @see https://stackoverflow.com/a/51082563/9122820
+ */
 export declare let useTraceUpdate: (props: any) => void;
 export default useTraceUpdate;

package/useUpdateEffect.d.ts CHANGED Viewed

@@ -1,3 +1,6 @@
 import { useEffect } from "react";
+/**
+ * @borrows [streamich/react-use](https://github.com/streamich/react-use/blob/master/src/useUpdateEffect.ts)
+ */
 export declare let useUpdateEffect: typeof useEffect;
 export default useUpdateEffect;

package/useWindowSize.d.ts CHANGED Viewed

@@ -1,3 +1,12 @@
 import { debounce } from "@koine/utils";
+/**
+ * # Use `window` size
+ *
+ * @param args Optionally pass {@link debounce} arguments (`wait` and `immediate`)
+ *
+ * @returns An array with:
+ * 1) _width_: using `window.innerWidth`
+ * 2) _height_: using `window.innerHeight`
+ */
 export declare let useWindowSize: (wait?: Parameters<typeof debounce>[1], immediate?: Parameters<typeof debounce>[2]) => readonly [number, number];
 export default useWindowSize;