@reykjavik/hanna-react 0.10.65 → 0.10.66

package/AccordionList.js

@@ -6,13 +6,15 @@ const hooks_1 = require("@hugsmidjan/react/hooks");
 const getBemClass_1 = tslib_1.__importDefault(require("@hugsmidjan/react/utils/getBemClass"));
 const seenEffect_1 = require("./utils/seenEffect");
 const AccordionListItem = (props) => {
-    const { title, content, id, disabled = false, defaultOpen, ssr } = props;
-    const [open, setOpen] = (0, react_1.useState)(defaultOpen);
-    (0, react_1.useEffect)(() => setOpen(defaultOpen), [defaultOpen]);
+    const { title, content, id, disabled = false, ssr } = props;
+    // TODO: Add controlled state support to this component, and then switch
+    // to usw the hooks exported from `utils/useMixecControlState.ts`
+    const [open, setOpen] = (0, react_1.useState)(props.defaultOpen);
+    const defaultOpen = (0, react_1.useRef)(props.defaultOpen);
     const domid = (0, hooks_1.useDomid)();
     const isBrowser = (0, hooks_1.useIsBrowserSide)(ssr);
     const itemDisabled = (isBrowser && disabled) || !content;
-    return (react_1.default.createElement("div", { className: (0, getBemClass_1.default)('AccordionList__item', [itemDisabled && 'disabled']), id: id, "data-start-open": defaultOpen || undefined, "data-sprinkled": isBrowser },
+    return (react_1.default.createElement("div", { className: (0, getBemClass_1.default)('AccordionList__item', [itemDisabled && 'disabled']), id: id, "data-start-open": defaultOpen.current, "data-sprinkled": isBrowser },
         react_1.default.createElement("h3", { className: "AccordionList__title" }, isBrowser ? (react_1.default.createElement("button", { type: "button", className: "AccordionList__button", "aria-controls": domid, "aria-expanded": open || undefined, onClick: () => {
                 setOpen(!open);
             }, disabled: itemDisabled }, title)) : (title)),

package/Alert.d.ts

@@ -1,5 +1,6 @@
 import { MouseEvent, ReactNode } from 'react';
 import { SSRSupport } from '@hugsmidjan/react/hooks';
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { DefaultTexts } from '@reykjavik/hanna-utils/i18n';
 export declare type AlertI18n = {
     closeLabel: string;
@@ -24,7 +25,7 @@ export declare type AlertProps = {
     texts?: AlertI18n;
     lang?: string;
     ssr?: SSRSupport;
-} & ({
+} & EitherObj<{
     /** Seconds until the Alert auto-closes.
      *
      * Mosueover and keyboard focus resets the timer.
@@ -34,8 +35,7 @@ export declare type AlertProps = {
     onClose?: () => void | boolean;
     /** Callback that fires when the alert has closed/transitoned out */
     onClosed: () => void;
-} | {
-    autoClose?: never;
+}, {
     /**
      * @deprecated This signature with the `event` argument will be removed in hanna-react v0.9
      *
@@ -44,6 +44,6 @@ export declare type AlertProps = {
     onClose?(event: MouseEvent): void | boolean;
     /** Callback that fires after the alert has closed/transitoned out */
     onClosed?(): void;
-});
+}>;
 declare const Alert: (props: AlertProps) => JSX.Element;
 export default Alert;

package/Alert.js

@@ -19,12 +19,10 @@ const useAutoClosing = (autoClose) => {
     const freeze = () => setTemp((temp) => temp - 1);
     return {
         autoClosing: temp === 0,
-        autoClosingProps: Object.assign({ onMouseEnter: freeze, onMouseLeave: thaw, onFocus: freeze, onBlur: thaw }, (env_1.isPreact
-            ? {
-                onfocusin: (e) => e.currentTarget !== e.target && freeze(),
-                onfocusout: (e) => e.currentTarget !== e.target && thaw(),
-            }
-            : undefined)),
+        autoClosingProps: Object.assign({ onMouseEnter: freeze, onMouseLeave: thaw, onFocus: freeze, onBlur: thaw }, (env_1.isPreact && {
+            onfocusin: (e) => e.currentTarget !== e.target && freeze(),
+            onfocusout: (e) => e.currentTarget !== e.target && thaw(),
+        })),
     };
 };
 exports.defaultAlertTexts = {

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 - ... <!-- Add new lines here. -->
 
+## 0.10.66
+
+_2022-09-01_
+
+- feat: Add `utils` hook `useDidChange`
+- feat: Add `utils` hook `useMixedControlState`
+- feat: Add `utils` hook `useScrollbarWidthCSSVar`
+- fix: Stop hard-resetting `AccordionList`'s state on `defaultOpen` changes
+
 ## 0.10.63 – 0.10.65
 
 _2022-08-29_

package/CityBlock.d.ts

@@ -1,3 +1,4 @@
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { Illustration } from '@reykjavik/hanna-utils/assets';
 import { BlockItem } from './_abstract/_Block';
 import { ImageProps } from './_abstract/_Image';
@@ -7,17 +8,14 @@ declare const types: {
     largebox: boolean;
     largeimage: boolean;
 };
-declare type CityBlockImageProps = {
-    illustration: Illustration;
-    image?: never;
-} | {
-    image: ImageProps;
-    illustration?: never;
-};
 export declare type CityBlockProps = {
     align?: Alignment;
     type?: keyof typeof types;
     content: BlockItem;
-} & CityBlockImageProps & SeenProp;
+} & EitherObj<{
+    illustration: Illustration;
+}, {
+    image: ImageProps;
+}> & SeenProp;
 declare const CityBlock: (props: CityBlockProps) => JSX.Element;
 export default CityBlock;

package/FileInput.js

@@ -102,9 +102,12 @@ const FileInput = (props) => {
                 // name prop is provided. This is implicitly what the
                 // browser does on form submit.
                 // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name
+                // In such cases we assume the application controls the upload/submit
+                // behavior separately outside of this component.
                 inputElementProps.name ? (react_1.default.createElement("input", { className: "FileInput__input", name: inputElementProps.name, id: domid, ref: fileInput, type: "file", style: { display: 'none' }, multiple: multiple || undefined, required: inputProps.required })) : null,
                 react_1.default.createElement("input", Object.assign({ 
-                    // fa
+                    // fake input exclusively used to capture clicks and file drops.
+                    // it's contents are wiped on every "add" action.
                     className: "FileInput__input--fake" }, getInputProps(), { tabIndex: undefined, style: undefined, multiple: multiple || undefined }, inputProps, { required: undefined })),
                 ' ',
                 react_1.default.createElement("div", Object.assign({ className: (0, getBemClass_1.default)('FileInput__dropzone', [isHover && 'highlight']) }, getRootProps({ isDragReject }), { tabIndex: undefined }),

package/IframeBlock.d.ts

@@ -1,20 +1,19 @@
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { ResizerOptions } from 'iframe-resizer-react';
 export declare type IframeBlockProps = {
     src: string;
     framed?: boolean;
     compact?: boolean;
     align?: 'right';
-} & ({
+} & EitherObj<{
     /** Default: `'auto'` ... which initializes "iframe-resizer" script */
     height?: 'auto';
-    scrolling?: never;
     /** Default: `false` ... Set to `true` for same-site only, or provide array of allowed domain-names */
     checkOrigin?: ResizerOptions['checkOrigin'];
-} | {
+}, {
     height: number;
     scrolling?: boolean | 'no' | 'yes';
-    checkOrigin?: never;
-});
+}>;
 /**
  * When `height` is undefined or "auto", then Add the following code-snipped to the iframed page:
  *

package/Layout.d.ts

@@ -2,6 +2,7 @@ import { ReactNode } from 'react';
 import { SSRSupport } from '@hugsmidjan/react/hooks';
 import { BemPropsModifier } from '@hugsmidjan/react/types';
 import { HannaColorTheme } from '@reykjavik/hanna-css';
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { DefaultTexts } from '@reykjavik/hanna-utils/i18n';
 export declare type LayoutI18n = {
     lang?: string;
@@ -22,12 +23,10 @@ declare type LayoutProps = {
     ssr?: SSRSupport;
     texts?: LayoutI18n;
     lang?: string;
-} & ({
+} & EitherObj<{
     mainChildren: ReactNode;
-    children?: never;
-} | {
-    mainChildren?: never;
+}, {
     children: ReactNode;
-});
+}>;
 declare const Layout: (props: LayoutProps) => JSX.Element;
 export default Layout;

package/PageFilter.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { SeenProp } from './utils/seenEffect';
 export declare type PageFilterProps = {
     title: string;
@@ -6,12 +7,10 @@ export declare type PageFilterProps = {
     footnote?: React.ReactNode;
     buttonRow?: React.ReactNode;
     underlap?: boolean;
-} & ({
+} & EitherObj<{
     filters: React.ReactNode;
-    children?: never;
-} | {
-    filters?: never;
+}, {
     children: React.ReactNode;
-}) & SeenProp;
+}> & SeenProp;
 declare const PageFilter: (props: PageFilterProps) => JSX.Element;
 export default PageFilter;

package/README.md

@@ -3,16 +3,21 @@
 The official React components for Hanna – Reykjavík's design-system
 
 ```
-npm install --save @reykjavik/hanna-react
+yarn add @reykjavik/hanna-react
 ```
 
+Components aim to be framework-agnostic and avoid unneccessary local state –
+always preferring "controlled" use.
+
+(See [README-conventions.md](./README-conventions.md) for more info.)
+
 ## Versioning
 
 This module always targets the most recent version of the Hanna markup
 patterns (currently **Hanna 0.8**).
 
 <!--
-	NOTE:
+	**NOTE:**
 	If need arises we may decide to branch the repo and publish separate
 	legacy modules (i.e. `@reykjavik/hanna_1-react`) that provide active
 	long-term-support for older major-versions of Hanna's markup patterns.
@@ -32,7 +37,7 @@ version, you'll find the appropriate package version in the
 ## CSS
 
 Each component is paired with a CSS file that can be loaded via the Hanna CSS
-server – https://styles.reykjavik.is/
+server – <https://styles.reykjavik.is>
 
 If your project uses `<Layout/>`, `<HeroBlock/>`, `<TextInput/>`,
 `<Selectbox/>` and `<ButtonPrimary/>` you can load the required CSS by linking

package/TagPill.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { ButtonProps } from './_abstract/_Button';
 declare const colors: {
     readonly normal: "";
@@ -12,16 +13,13 @@ export declare type TagPillProps = ButtonProps & {
     children?: ReactNode;
     large?: boolean;
     color?: TagPillColor;
-} & ({
+} & EitherObj<{
     removable?: false;
-    onRemove?: never;
-    removeLabel?: never;
-    removeLabelLong?: never;
-} | {
+}, {
     removable: true;
     onRemove?: () => void;
     removeLabel?: string;
     removeLabelLong?: string;
-});
+}>;
 declare const TagPill: (props: TagPillProps) => JSX.Element;
 export default TagPill;

package/VSpacer.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { EitherObj } from '@reykjavik/hanna-utils';
 declare const sizes: {
     readonly none: "none";
     readonly small: "small";
@@ -9,16 +10,13 @@ declare const sizes: {
 };
 declare type VSpacerSize = keyof typeof sizes;
 declare type VSpacerSizePos = Exclude<VSpacerSize, 'none'>;
-export declare type VSpacerProps = {
-    children?: never;
+export declare type VSpacerProps = EitherObj<{
     size?: VSpacerSizePos;
-    top?: never;
-    bottom?: never;
-} | {
+}, {
     children: ReactNode;
     size?: VSpacerSizePos;
     top?: VSpacerSize;
     bottom?: VSpacerSize;
-};
+}>;
 declare const VSpacer: (props: VSpacerProps) => JSX.Element;
 export default VSpacer;

package/_abstract/_AbstractCarousel.d.ts

@@ -1,23 +1,20 @@
 import { ReactElement } from 'react';
 import { SSRSupport } from '@hugsmidjan/react/hooks';
 import { BemProps } from '@hugsmidjan/react/types';
+import { EitherObj } from '@reykjavik/hanna-utils';
 import { SeenProp } from '../utils/seenEffect';
 export declare type CarouselProps<I extends Record<string, unknown> = {}, P extends Record<string, unknown> | undefined = {}> = {
     className?: string;
     ssr?: SSRSupport;
     /** @deprecated Ingored because never used (Will be removed in v0.11) */
     scrollRight?: boolean;
-} & ({
-    children?: never;
+} & EitherObj<{
     items: Array<I>;
     Component: (props: P extends undefined ? I : I & P) => ReactElement | null;
     ComponentProps?: P;
-} | {
+}, {
     children: Array<ReactElement>;
-    items?: never;
-    Component?: never;
-    ComponentProps?: never;
-}) & SeenProp;
+}> & SeenProp;
 declare type AbstractCarouselProps<I extends Record<string, unknown> = {}, P extends Record<string, unknown> | undefined = {}> = CarouselProps<I, P> & BemProps & {
     title?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reykjavik/hanna-react",
-	"version": "0.10.65",
+	"version": "0.10.66",
 	"author": "Reykjavík (http://www.reykjavik.is)",
 	"contributors": [
 		"Hugsmiðjan ehf (http://www.hugsmidjan.is)",
@@ -16,7 +16,7 @@
 		"@hugsmidjan/qj": "^4.10.2",
 		"@hugsmidjan/react": "^0.4.17",
 		"@reykjavik/hanna-css": "^0.3.7",
-		"@reykjavik/hanna-utils": "^0.1.11",
+		"@reykjavik/hanna-utils": "^0.1.12",
 		"@types/react": "^17.0.24",
 		"@types/react-autosuggest": "^10.1.0",
 		"@types/react-datepicker": "^3.0.2",

package/utils/useDidChange.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reports if value changed since last time the hook was called.
+ *
+ * Returns an `{ lastValue }` shaped object, when change is detected.
+ * Returns `undefined` otherwise
+ *
+ * Common usage is if you want an component which is effectively uncontrolled,
+ * but resets/changes its internal state whenever a certain prop value changes.
+ *
+ * ```tsx
+ * import { useDidChange } from './utils';
+ * // import { useDidChange } from '@reykjavik/hanna-react/utils';
+ *
+ * // inside your component/hook
+ * const [visible, setVisible] = useState(props.visible);
+ * if (useDidChange(props.visible)) {
+ *   setVisible(props.visible);
+ * }
+ * ```
+ *
+ * Another use case might be to capture not only IF but HOW a prop value changed
+ * in a controlled component
+ *
+ * ```tsx
+ * const [trend, setTrend] = useState(null);
+ * const countChanged = useDidChange(props.count);
+ * if (countChanged) {
+ *   setTrend(props.count > countChanged.lastValue ? 'increasing' : 'decreasing');
+ * }
+ * ```
+ *
+ * **NOTE:** This hook should be handled with care, as its overuse can easily lead
+ * to poorly structured and buggy component behavior.
+ */
+export declare const useDidChange: <T>(value: T) => {
+    lastValue: T;
+} | undefined;

package/utils/useDidChange.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDidChange = void 0;
+const react_1 = require("react");
+/**
+ * Reports if value changed since last time the hook was called.
+ *
+ * Returns an `{ lastValue }` shaped object, when change is detected.
+ * Returns `undefined` otherwise
+ *
+ * Common usage is if you want an component which is effectively uncontrolled,
+ * but resets/changes its internal state whenever a certain prop value changes.
+ *
+ * ```tsx
+ * import { useDidChange } from './utils';
+ * // import { useDidChange } from '@reykjavik/hanna-react/utils';
+ *
+ * // inside your component/hook
+ * const [visible, setVisible] = useState(props.visible);
+ * if (useDidChange(props.visible)) {
+ *   setVisible(props.visible);
+ * }
+ * ```
+ *
+ * Another use case might be to capture not only IF but HOW a prop value changed
+ * in a controlled component
+ *
+ * ```tsx
+ * const [trend, setTrend] = useState(null);
+ * const countChanged = useDidChange(props.count);
+ * if (countChanged) {
+ *   setTrend(props.count > countChanged.lastValue ? 'increasing' : 'decreasing');
+ * }
+ * ```
+ *
+ * **NOTE:** This hook should be handled with care, as its overuse can easily lead
+ * to poorly structured and buggy component behavior.
+ */
+const useDidChange = (value) => {
+    const lastValueRef = (0, react_1.useRef)(value);
+    const lastValue = lastValueRef.current;
+    if (value !== lastValue) {
+        lastValueRef.current = value;
+        return { lastValue };
+    }
+};
+exports.useDidChange = useDidChange;

package/utils/useMixedControlState.d.ts

@@ -0,0 +1,75 @@
+import { Dispatch, SetStateAction } from 'react';
+declare type DefaultProp<N extends string> = `default${Capitalize<N>}`;
+declare type PropPair<N extends string> = N | DefaultProp<N>;
+declare type StrictKeys<P extends Record<string, unknown>, N extends string> = PropPair<N> extends keyof P ? P : {
+    [Key in PropPair<N>]: P[Key];
+};
+/**
+ * State hook to simplify dealing with a the complexities of supporting a mixture
+ * of "controlled" and "uncontrolled" component state.
+ *
+ * The returned value and dispatcher/setter function return the controlled
+ * `value`, but gracefully handle changes in defaultValue in uncontrolled mode,
+ * and handles (unexpected) "mode-changes" in a predictable manner.
+ *
+ * It assumes (by default) that the calling component has
+ * a pair of props following the naming convention `foo` and `defaultFoo` —
+ * similar to React's own `<input/>` and `<select/>` HTML components warn about
+ * their `value` and `defaultValue` props being misused.
+ *
+ * NOTE: This hook also exposes a slightly lower-level helper hook
+ * `useMixedControlState.raw(value, defaultValue)`, for cases where you don't
+ * have a neatly-shaped props object as described above, or you need to do
+ * some sort of pre-processing of either prop value.
+ *
+ * ```tsx
+ * import React, { FC, ReactNode } from 'react';
+ * import { useMixedControlState } from '@reykjavik/hanna-react/utils';
+ *
+ * type FooBarProps = {
+ *   visible?: boolean;
+ *   onChange?: (newVisible: boolean) => void;
+ *   defaultVisible?: boolean;
+ * };
+ *
+ * export const FooBar: FC<FooBarProps> = (props) => {
+ *   const [visible, setVisible] = useMixedControlState(props, 'visible', true);
+ *
+ *   const handleToggle = () => {
+ *     props.onChange?.(!visible);
+ *     setVisible(!visible);
+ *   };
+ *   return (
+ *     <div>
+ *       <button onClick={handleToggle}>Toggle</button>
+ *       <div hidden={!visible}>{props.children}</div>
+ *     </div>
+ *   );
+ * };
+ * ```
+ */
+export declare const useMixedControlState: {
+    <N extends string, P extends { [x in PropPair<N>]?: unknown; }>(props: StrictKeys<P, N>, name: N, defaultDefault?: P[`default${Capitalize<N>}`] | undefined): [StrictKeys<P, N>[N] | StrictKeys<P, N>[`default${Capitalize<N>}`] | undefined, Dispatch<SetStateAction<StrictKeys<P, N>[N] | StrictKeys<P, N>[`default${Capitalize<N>}`] | undefined>>];
+    /**
+     * a slightly lower-level hook alternative to
+     * `useMixedControlState(props, name)`, for cases where you don't
+     * have a neatly-/conventionally-shaped props object, or if you need to do
+     * some sort of pre-processing of either prop value.
+     *
+     * ```tsx
+     * import { useMixedControlState } from '@reykjavik/hanna-react/utils';
+     *
+     * declare const props: { visible?: boolean; defaultVisible?: boolean };
+     *
+     * const [vislble, setVisible] = useMixedControlState.raw(
+     *    props.vislble,
+     *    props.defaultVisible,
+     *    'visible'
+     * );
+     * // has the same effect as this:
+     * const [visible, setVisible] = useMixedControlState(props, 'visible');
+     * ```
+     */
+    raw<C, U>(value: C, defaultValue: U, warningPropName?: string): [C | U, Dispatch<SetStateAction<C | U>>];
+};
+export {};

package/utils/useMixedControlState.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMixedControlState = void 0;
+const react_1 = require("react");
+const hanna_utils_1 = require("@reykjavik/hanna-utils");
+// ---------------------------------------------------------------------------
+/**
+ * State hook to simplify dealing with a the complexities of supporting a mixture
+ * of "controlled" and "uncontrolled" component state.
+ *
+ * The returned value and dispatcher/setter function return the controlled
+ * `value`, but gracefully handle changes in defaultValue in uncontrolled mode,
+ * and handles (unexpected) "mode-changes" in a predictable manner.
+ *
+ * It assumes (by default) that the calling component has
+ * a pair of props following the naming convention `foo` and `defaultFoo` —
+ * similar to React's own `<input/>` and `<select/>` HTML components warn about
+ * their `value` and `defaultValue` props being misused.
+ *
+ * NOTE: This hook also exposes a slightly lower-level helper hook
+ * `useMixedControlState.raw(value, defaultValue)`, for cases where you don't
+ * have a neatly-shaped props object as described above, or you need to do
+ * some sort of pre-processing of either prop value.
+ *
+ * ```tsx
+ * import React, { FC, ReactNode } from 'react';
+ * import { useMixedControlState } from '@reykjavik/hanna-react/utils';
+ *
+ * type FooBarProps = {
+ *   visible?: boolean;
+ *   onChange?: (newVisible: boolean) => void;
+ *   defaultVisible?: boolean;
+ * };
+ *
+ * export const FooBar: FC<FooBarProps> = (props) => {
+ *   const [visible, setVisible] = useMixedControlState(props, 'visible', true);
+ *
+ *   const handleToggle = () => {
+ *     props.onChange?.(!visible);
+ *     setVisible(!visible);
+ *   };
+ *   return (
+ *     <div>
+ *       <button onClick={handleToggle}>Toggle</button>
+ *       <div hidden={!visible}>{props.children}</div>
+ *     </div>
+ *   );
+ * };
+ * ```
+ */
+const useMixedControlState = (
+/** The props object of your component  */
+props, 
+/** Name of the prop for the controlled value */
+name, 
+/**
+ * A last-resort default value for the defaultValue prop
+ *
+ * Used as uncontrolled default if the `default${capitalize(name)}` value
+ * of `props` is missing/undefined.
+ */
+defaultDefault) => {
+    let defaultValue = props[`default${(0, hanna_utils_1.capitalize)(name)}`];
+    if (defaultValue === undefined) {
+        defaultValue = defaultDefault;
+    }
+    return exports.useMixedControlState.raw(props[name], defaultValue, name);
+};
+exports.useMixedControlState = useMixedControlState;
+// ---------------------------------------------------------------------------
+/**
+ * a slightly lower-level hook alternative to
+ * `useMixedControlState(props, name)`, for cases where you don't
+ * have a neatly-/conventionally-shaped props object, or if you need to do
+ * some sort of pre-processing of either prop value.
+ *
+ * ```tsx
+ * import { useMixedControlState } from '@reykjavik/hanna-react/utils';
+ *
+ * declare const props: { visible?: boolean; defaultVisible?: boolean };
+ *
+ * const [vislble, setVisible] = useMixedControlState.raw(
+ *    props.vislble,
+ *    props.defaultVisible,
+ *    'visible'
+ * );
+ * // has the same effect as this:
+ * const [visible, setVisible] = useMixedControlState(props, 'visible');
+ * ```
+ */
+exports.useMixedControlState.raw = (
+/** Controlled value. */
+value, 
+/** Default/initial value for uncontrolled use. */
+defaultValue, 
+/**
+ * Prop name to display more meaningful warnings about when value
+ * and defaultValue are both defined, or if the component switches
+ * between modes mid-stream.
+ *
+ * If left undefined, the hook emits more generic/vague warnings
+ */
+warningPropName) => {
+    /* eslint-disable react-hooks/rules-of-hooks */
+    const meta = (0, react_1.useRef)({
+        lastMode: undefined,
+        lastDefault: defaultValue,
+        // lastValue: value,
+    }).current;
+    const { lastMode, lastDefault /*,  lastValue  */ } = meta;
+    const mode = value !== undefined
+        ? 'controlled'
+        : defaultValue !== undefined
+            ? 'uncontrolled'
+            : lastMode;
+    // Validate sane use of the component, during development.
+    if (process.env.NODE_ENV !== 'production') {
+        if (value !== undefined && defaultValue !== undefined) {
+            console.error(`WARNING:` +
+                ` Don't mix` +
+                (warningPropName
+                    ? ` \`${warningPropName}\` and \`default${(0, hanna_utils_1.capitalize)(warningPropName)}\` props`
+                    : 'controlled and uncontrolled mode') +
+                `\n` +
+                `Use one or the other.`);
+        }
+        if (lastMode && lastMode !== mode) {
+            console.error(`WARNING:` +
+                `A component is changing from ${lastMode} to ${mode} mode.` +
+                `\n` +
+                (warningPropName
+                    ? `Decide between using \`${warningPropName}\` (controlled) prop` +
+                        ` OR \`default${(0, hanna_utils_1.capitalize)(warningPropName)}\` (uncontrolled)`
+                    : `Decide between using either controlled OR uncontrolled mode`) +
+                ` for the lifetime of the component.`);
+        }
+    }
+    const [localValue, _setLocalValue] = (0, react_1.useState)(defaultValue);
+    const setLocalValue = (0, react_1.useCallback)((newState) => {
+        if (mode === 'controlled' && typeof newState === 'function') {
+            // @ts-expect-error  (TS needs a bit of help here, it seems,
+            // because the C and U gernerics are too …err… generic?)
+            const action = newState;
+            newState = action(value);
+        }
+        _setLocalValue.$called = true;
+        _setLocalValue(newState);
+    }, [value, mode]);
+    // The mode can change but it should never go back to `undefined` state
+    // this is similar to what React does with it's <input> and <select>
+    // elements.
+    // In dev-mode an WARNING gets logged whenever the mode changes.
+    meta.lastMode = mode;
+    if (mode === 'uncontrolled') {
+        // only update lastDefault when in unconrolled mode
+        // to guarantee capture of changes that might happen during
+        // controlled mode. Something that should ideally not happen
+        // but is worth keeping as sane as possible nonetheless.
+        meta.lastDefault = defaultValue;
+        if (!_setLocalValue.$called && defaultValue !== lastDefault) {
+            _setLocalValue(defaultValue); // Immediately exits and re-renders the component
+        }
+    }
+    // meta.lastValue = value;
+    const retValue = mode === 'controlled' ? value : localValue;
+    return [retValue, setLocalValue];
+    /* eslint-enable react-hooks/rules-of-hooks */
+};

package/utils/useScrollbarWidthCSSVar.d.ts

@@ -1 +1,17 @@
+/**
+ * Measures the scrollbar width and sets it as a CSS variable on
+ * the `<html/>` element.
+ *
+ * Use this hook inside all of your top-level layout components
+ *
+ * The name of the variable is `--browser-scrollbar-width`, and you can
+ * reference it manually in your CSS, or via the hanna-css variable helper.
+ *
+ * ```ts
+ * import { hannaVars } from '@reykjavik/hanna-css';
+ *
+ * console.log(hannaVars.browser_scrollbar_width.toString())
+ * // "var(--browser-scrollbar-width)"
+ * ```
+ */
 export declare const useScrollbarWidthCSSVar: () => void;

package/utils/useScrollbarWidthCSSVar.js

@@ -2,7 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useScrollbarWidthCSSVar = void 0;
 const tslib_1 = require("tslib");
+const react_1 = require("react");
 const getScrollbarWidth_1 = tslib_1.__importDefault(require("@hugsmidjan/qj/getScrollbarWidth"));
-const hooks_1 = require("@hugsmidjan/react/hooks");
-const useScrollbarWidthCSSVar = () => (0, hooks_1.useOnMount)(() => getScrollbarWidth_1.default.setCSSvar());
+/**
+ * Measures the scrollbar width and sets it as a CSS variable on
+ * the `<html/>` element.
+ *
+ * Use this hook inside all of your top-level layout components
+ *
+ * The name of the variable is `--browser-scrollbar-width`, and you can
+ * reference it manually in your CSS, or via the hanna-css variable helper.
+ *
+ * ```ts
+ * import { hannaVars } from '@reykjavik/hanna-css';
+ *
+ * console.log(hannaVars.browser_scrollbar_width.toString())
+ * // "var(--browser-scrollbar-width)"
+ * ```
+ */
+const useScrollbarWidthCSSVar = () => (0, react_1.useEffect)(() => getScrollbarWidth_1.default.setCSSvar(), []);
 exports.useScrollbarWidthCSSVar = useScrollbarWidthCSSVar;

package/utils.d.ts

@@ -1,2 +1,5 @@
+export * from './utils/useDidChange';
 export * from './utils/useFormatMonitor';
 export * from './utils/useGetSVGtext';
+export * from './utils/useMixedControlState';
+export * from './utils/useScrollbarWidthCSSVar';

package/utils.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./utils/useDidChange"), exports);
 tslib_1.__exportStar(require("./utils/useFormatMonitor"), exports);
 tslib_1.__exportStar(require("./utils/useGetSVGtext"), exports);
+tslib_1.__exportStar(require("./utils/useMixedControlState"), exports);
+tslib_1.__exportStar(require("./utils/useScrollbarWidthCSSVar"), exports);