tinywidgets 1.3.12 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinywidgets",
-  "version": "1.3.12",
+  "version": "1.5.0",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinywidgets",
   "license": "MIT",
@@ -22,26 +22,30 @@
     "@eslint/js": "^9.30.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "cspell": "^9.7.0",
+    "cspell": "^10.0.0",
     "eslint": "^9.30.1",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "globals": "^17.4.0",
-    "prettier": "^3.8.1",
+    "globals": "^17.5.0",
+    "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1"
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.58.2"
   },
   "exports": {
     ".": "./src/index.ts",
     "./css": "./src/index.css.ts"
   },
   "dependencies": {
-    "@vanilla-extract/css": "^1.19.1",
-    "lucide-react": "^0.577.0",
+    "@vanilla-extract/css": "^1.20.1",
+    "lucide-react": "^1.8.0",
+    "tinybase": "^8.2.0"
+  },
+  "peerDependencies": {
     "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "tinybase": "^8.0.2"
+    "react-dom": "^19.2.4"
   }
-}
+}

package/src/common/functions.tsx

@@ -1,5 +1,10 @@
 import type {StyleRule} from '@vanilla-extract/css';
-import {type ComponentType, type ReactNode} from 'react';
+import {
+  createElement,
+  isValidElement,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
 import {screens} from '../css/screens';
 
 /**
@@ -30,12 +35,18 @@ export const classNames = (
 export const renderComponentOrNode = (
   ComponentOrNode: ComponentType | ReactNode,
   fallback: ReactNode = null,
-) =>
-  ComponentOrNode instanceof Function ? (
-    <ComponentOrNode />
-  ) : (
-    (ComponentOrNode ?? fallback)
-  );
+): ReactNode => {
+  if (ComponentOrNode == null) {
+    return fallback;
+  }
+  if (isValidElement(ComponentOrNode)) {
+    return ComponentOrNode;
+  }
+  if (['string', 'number', 'boolean'].includes(typeof ComponentOrNode)) {
+    return ComponentOrNode as string | number | boolean;
+  }
+  return createElement(ComponentOrNode as ComponentType);
+};
 
 export const large = (style: StyleRule) => ({
   '@media': {[`screen and (min-width: ${screens.large}px)`]: style},

package/src/components/App/index.css.ts

@@ -12,9 +12,7 @@ export const appLayout = style({
 });
 
 export const header = style({
-  display: 'flex',
   justifyContent: 'space-between',
-  alignItems: 'center',
   gap: dimensions.padding,
   padding: dimensions.padding,
   position: 'fixed',
@@ -29,9 +27,7 @@ export const header = style({
 });
 
 export const topNav = style({
-  display: 'flex',
   justifyContent: 'space-between',
-  alignItems: 'center',
   gap: dimensions.padding,
   flex: 1,
 });
@@ -39,9 +35,6 @@ export const topNav = style({
 export const sideNavButton = style(large({display: 'none!important'}));
 
 export const title = style({
-  display: 'flex',
-  alignItems: 'center',
-  gap: dimensions.padding,
   ...large({
     width: `calc(${dimensions.sideNavWidth} - 2 * ${dimensions.padding})`,
   }),
@@ -84,9 +77,7 @@ export const mainHasFooter = style({
 });
 
 export const footer = style({
-  display: 'flex',
   justifyContent: 'right',
-  alignItems: 'center',
   gap: dimensions.padding,
   paddingLeft: dimensions.padding,
   paddingRight: dimensions.padding,

package/src/components/App/index.tsx

@@ -25,6 +25,7 @@ import {
   useSideNavIsOpen,
   useToggleSideNavIsOpenCallback,
 } from '../../stores/SessionStore.tsx';
+import {Axis} from '../Axis/index.tsx';
 import {Button} from '../Button/index.tsx';
 import {
   app,
@@ -165,7 +166,7 @@ const Layout = ({
         <LayoutContext.Provider value={{portal: ref.current}}>
           {sessionStoreIsReady && routeStoreIsReady && localStoreIsReady ? (
             <>
-              <header className={header}>
+              <Axis as="header" className={header}>
                 {hasSideNav ? (
                   <Button
                     variant="icon"
@@ -177,10 +178,10 @@ const Layout = ({
                 <nav className={title}>
                   {renderComponentOrNode(titleComponentOrNode)}
                 </nav>
-                <nav className={topNav}>
+                <Axis as="nav" className={topNav}>
                   {renderComponentOrNode(topNavLeftComponentOrNode, <div />)}
                   {renderComponentOrNode(topNavRightComponentOrNode, <div />)}
-                </nav>
+                </Axis>
                 <Button
                   variant="icon"
                   onClick={toggleDarkChoice}
@@ -197,7 +198,7 @@ const Layout = ({
                     {renderComponentOrNode(sideNavComponentOrNode)}
                   </nav>
                 ) : null}
-              </header>
+              </Axis>
               <main
                 className={classNames(
                   main,
@@ -208,9 +209,9 @@ const Layout = ({
                 {renderComponentOrNode(mainComponentOrNode)}
               </main>
               {hasFooter ? (
-                <footer className={footer}>
+                <Axis as="footer" className={footer}>
                   {renderComponentOrNode(footerComponentOrNode)}
-                </footer>
+                </Axis>
               ) : null}
             </>
           ) : null}

package/src/components/Axis/index.css.ts

@@ -0,0 +1,13 @@
+import {style, styleVariants} from '@vanilla-extract/css';
+
+export const axis = style({
+  display: 'flex',
+  alignItems: 'center',
+});
+
+export const axisVariants = styleVariants({
+  horizontal: {},
+  vertical: {
+    flexDirection: 'column',
+  },
+});

package/src/components/Axis/index.tsx

@@ -0,0 +1,82 @@
+import type {MouseEventHandler, ReactNode} from 'react';
+import {classNames} from '../../common/functions';
+import {axis, axisVariants} from './index.css';
+
+/**
+ * The `Axis` component displays its children along a flex axis, aligning them
+ * in the center of the cross-axis.
+ *
+ * This is useful for compact layouts where icons, avatars, images, and text
+ * should share a common visual center line, or for stacked layouts that should
+ * remain horizontally centered.
+ *
+ * @param props The props for the component.
+ * @returns The Axis component.
+ * @example
+ * ```tsx
+ * <Axis>
+ *   <Image src="/favicon.svg" variant="logo" />
+ *   TinyWidgets
+ * </Axis>
+ * ```
+ * This example shows a logo image and text aligned along the same
+ * horizontal axis.
+ * @example
+ * ```tsx
+ * <Axis variant="vertical">
+ *   <Image src="/favicon.svg" variant="logo" />
+ *   TinyWidgets
+ * </Axis>
+ * ```
+ * This example shows the same content arranged on a vertical axis.
+ * @icon Lucide.AlignCenterHorizontal
+ */
+export const Axis = ({
+  as: Component = 'div',
+  variant = 'horizontal',
+  className,
+  title,
+  onClick,
+  children,
+}: {
+  /**
+   * The HTML element used to wrap the axis, one of:
+   * - `div`
+   * - `nav`
+   * - `span`
+   * - `h1`
+   * - `header`
+   * - `footer`
+   */
+  readonly as?: 'div' | 'nav' | 'span' | 'h1' | 'header' | 'footer';
+  /**
+   * A variant of the axis, one of:
+   * - `horizontal`
+   * - `vertical`
+   */
+  readonly variant?: keyof typeof axisVariants;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+  /**
+   * Alternative text shown when the user hovers over the component.
+   */
+  readonly title?: string;
+  /**
+   * A handler called when the user clicks on the component.
+   */
+  readonly onClick?: MouseEventHandler<HTMLElement>;
+  /**
+   * The children of the component, arranged along the selected axis.
+   */
+  readonly children: ReactNode;
+}) => (
+  <Component
+    className={classNames(axis, axisVariants[variant], className)}
+    title={title}
+    onClick={onClick}
+  >
+    {children}
+  </Component>
+);

package/src/components/ImageLabel/index.css.ts

@@ -0,0 +1,5 @@
+import {style} from '@vanilla-extract/css';
+
+export const imageLabel = style({
+  gap: '0.5rem',
+});

package/src/components/ImageLabel/index.tsx

@@ -0,0 +1,72 @@
+import type {ComponentType, MouseEventHandler, ReactNode} from 'react';
+import {classNames, renderComponentOrNode} from '../../common/functions';
+import {Axis} from '../Axis';
+import {imageLabel} from './index.css';
+
+/**
+ * The `ImageLabel` component displays an image and a text label along a shared
+ * horizontal axis.
+ *
+ * It is useful for common UI patterns such as brand marks, avatars with names,
+ * or any compact media-and-label combination.
+ *
+ * @param props The props for the component.
+ * @returns The ImageLabel component.
+ * @example
+ * ```tsx
+ * <ImageLabel
+ *   image={<Image src="/favicon.svg" variant="avatar" />}
+ *   text="TinyWidgets"
+ * />
+ * ```
+ * This example shows a logo image with a text label.
+ * @example
+ * ```tsx
+ * <ImageLabel
+ *   as="h1"
+ *   image={<Image src="/favicon.svg" variant="logo"/>}
+ *   text={<b>TinyWidgets</b>}
+ * />
+ * ```
+ * This example shows the component used as a heading with rich text content.
+ * @icon Lucide.Captions
+ */
+export const ImageLabel = ({
+  as = 'div',
+  image,
+  text,
+  className,
+  onClick,
+}: {
+  /**
+   * The HTML element used to wrap the image label, one of:
+   * - `div`
+   * - `nav`
+   * - `span`
+   * - `h1`
+   * - `header`
+   * - `footer`
+   */
+  readonly as?: 'div' | 'nav' | 'span' | 'h1' | 'header' | 'footer';
+  /**
+   * A component or element which renders the image for the label.
+   */
+  readonly image: ComponentType | ReactNode;
+  /**
+   * A component, element, or string which renders the label text.
+   */
+  readonly text: ComponentType | ReactNode;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+  /**
+   * A handler called when the user clicks on the component.
+   */
+  readonly onClick?: MouseEventHandler<HTMLElement>;
+}) => (
+  <Axis as={as} className={classNames(imageLabel, className)} onClick={onClick}>
+    {renderComponentOrNode(image)}
+    {renderComponentOrNode(text)}
+  </Axis>
+);

package/src/components/Loading/index.css.ts

@@ -0,0 +1,84 @@
+import {keyframes, style} from '@vanilla-extract/css';
+import {colors} from '../../css/colors.css';
+import {dimensions} from '../../css/dimensions.css';
+
+const spin = keyframes({
+  from: {transform: 'rotate(0deg)'},
+  to: {transform: 'rotate(360deg)'},
+});
+
+const shimmer = keyframes({
+  from: {transform: 'translateX(-100%)'},
+  to: {transform: 'translateX(100%)'},
+});
+
+export const loading = style({
+  display: 'grid',
+  gridTemplateRows: 'auto minmax(0, 1fr)',
+  gap: `calc(${dimensions.padding} / 1.5)`,
+  alignContent: 'start',
+});
+
+export const header = style({
+  display: 'flex',
+  alignItems: 'center',
+  gap: `calc(${dimensions.padding} / 2)`,
+  color: colors.foregroundDim,
+});
+
+export const spinner = style({
+  width: dimensions.icon,
+  height: dimensions.icon,
+  borderRadius: '999px',
+  border: `2px solid ${colors.backgroundHover}`,
+  borderTopColor: colors.accent,
+  animation: `${spin} .9s linear infinite`,
+  '@media': {
+    '(prefers-reduced-motion: reduce)': {
+      animation: 'none',
+    },
+  },
+});
+
+export const label = style({
+  fontSize: '.95rem',
+});
+
+export const rows = style({
+  position: 'relative',
+  display: 'grid',
+  gap: `calc(${dimensions.padding} / 2)`,
+  minHeight: 0,
+  overflow: 'hidden',
+});
+
+export const row = style({
+  position: 'relative',
+  overflow: 'hidden',
+  height: '.875rem',
+  borderRadius: dimensions.radius,
+  background: colors.background2,
+  selectors: {
+    '&::after': {
+      content: '""',
+      position: 'absolute',
+      inset: 0,
+      background: `linear-gradient(
+        90deg,
+        transparent,
+        ${colors.backgroundHover},
+        transparent
+      )`,
+      animation: `${shimmer} 1.6s ease-in-out infinite`,
+    },
+  },
+  '@media': {
+    '(prefers-reduced-motion: reduce)': {
+      selectors: {
+        '&::after': {
+          animation: 'none',
+        },
+      },
+    },
+  },
+});

package/src/components/Loading/index.tsx

@@ -0,0 +1,137 @@
+import {useEffect, useRef, useState} from 'react';
+import {classNames} from '../../common/functions';
+import {
+  header,
+  label,
+  loading,
+  row,
+  rows as rowsClass,
+  spinner,
+} from './index.css';
+
+const WIDTHS = ['100%', '92%', '84%', '96%', '72%', '88%', '67%', '81%'];
+const DEFAULT_ROW_COUNT = 5;
+
+/**
+ * The `Loading` component displays a compact spinner with optional shimmer rows
+ * to reserve space while content is loading.
+ *
+ * @param props The props for the component.
+ * @returns The Loading component.
+ * @example
+ * ```tsx
+ * <Loading labelText="Loading dependencies" />
+ * ```
+ * This example shows the default loading panel. Add a CSS height to the
+ * component to fit more placeholder rows automatically.
+ * @example
+ * ```tsx
+ * <>
+ *   <style>{`
+ *     .tallLoading {
+ *       height: 12rem;
+ *     }
+ *   `}</style>
+ *   <Loading className="tallLoading" labelText="Loading dependencies" />
+ * </>
+ * ```
+ * This example uses CSS to make the loading panel taller, allowing more
+ * placeholder rows to fit automatically.
+ * @icon Lucide.LoaderCircle
+ */
+export const Loading = ({
+  labelText = 'Loading',
+  className,
+}: {
+  /**
+   * The label shown beside the spinner.
+   */
+  readonly labelText?: string;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+}) => {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const headerRef = useRef<HTMLDivElement>(null);
+  const rowsRef = useRef<HTMLDivElement>(null);
+  const measureRowRef = useRef<HTMLDivElement>(null);
+
+  const [rowCount, setRowCount] = useState(DEFAULT_ROW_COUNT);
+
+  useEffect(() => {
+    const updateRowCount = () => {
+      const root = rootRef.current;
+      const header = headerRef.current;
+      const rows = rowsRef.current;
+      const measureRow = measureRowRef.current;
+      if (
+        root == null ||
+        header == null ||
+        rows == null ||
+        measureRow == null
+      ) {
+        return;
+      }
+
+      const rootStyles = getComputedStyle(root);
+      const rowsStyles = getComputedStyle(rows);
+      const rootGap =
+        parseFloat(rootStyles.rowGap || rootStyles.gap || '0') || 0;
+      const rowsGap =
+        parseFloat(rowsStyles.rowGap || rowsStyles.gap || '0') || 0;
+      const availableHeight =
+        root.getBoundingClientRect().height -
+        header.getBoundingClientRect().height -
+        rootGap;
+      const rowHeight = measureRow.getBoundingClientRect().height;
+
+      const nextRowCount = Math.max(
+        0,
+        Math.floor((availableHeight + rowsGap) / (rowHeight + rowsGap)),
+      );
+      setRowCount((currentRowCount) =>
+        currentRowCount === nextRowCount ? currentRowCount : nextRowCount,
+      );
+    };
+
+    updateRowCount();
+    if (typeof ResizeObserver === 'undefined') {
+      return;
+    }
+
+    const resizeObserver = new ResizeObserver(updateRowCount);
+    if (rootRef.current != null) {
+      resizeObserver.observe(rootRef.current);
+    }
+    if (headerRef.current != null) {
+      resizeObserver.observe(headerRef.current);
+    }
+    return () => resizeObserver.disconnect();
+  }, []);
+
+  return (
+    <div ref={rootRef} className={classNames(loading, className)}>
+      <div ref={headerRef} className={header}>
+        <span className={spinner} />
+        <span className={label}>{labelText}</span>
+      </div>
+      <div ref={rowsRef} className={rowsClass}>
+        <div
+          ref={measureRowRef}
+          className={row}
+          style={{position: 'absolute', width: 0, visibility: 'hidden'}}
+        />
+        {rowCount > 0
+          ? Array.from({length: rowCount}, (_, index) => (
+              <div
+                key={index}
+                className={row}
+                style={{width: WIDTHS[index % WIDTHS.length]}}
+              />
+            ))
+          : null}
+      </div>
+    </div>
+  );
+};

package/src/components/Metric/index.css.ts

@@ -7,8 +7,6 @@ export const metric = style({
 });
 
 export const metricLabel = style({
-  display: 'flex',
-  alignItems: 'center',
   gap: '0.5rem',
 });
 

package/src/components/Metric/index.tsx

@@ -1,6 +1,7 @@
 import type {ComponentType, ReactNode} from 'react';
 import {classNames, renderComponentOrNode} from '../../common/functions';
 import {iconSize} from '../../css/dimensions.css';
+import {Axis} from '../Axis';
 import {metric, metricLabel, metricNumber} from './index.css';
 
 /**
@@ -47,10 +48,10 @@ export const Metric = ({
   readonly className?: string;
 }) => (
   <div className={classNames(metric, className)}>
-    <div className={metricLabel}>
+    <Axis className={metricLabel}>
       {Icon ? <Icon className={iconSize} /> : null}
       {renderComponentOrNode(titleComponentOrNode)}
-    </div>
+    </Axis>
     <div className={metricNumber}>
       {renderComponentOrNode(numberComponentOrNode)}
     </div>

package/src/components/Tag/index.css.ts

@@ -2,8 +2,6 @@ import {style, styleVariants} from '@vanilla-extract/css';
 import {colors} from '../../css/colors.css';
 
 export const tag = style({
-  display: 'flex',
-  alignItems: 'center',
   fontSize: '0.625rem',
   lineHeight: '0.625rem',
   padding: '0.1rem 0.25rem',

package/src/components/Tag/index.tsx

@@ -1,5 +1,6 @@
 import type {ComponentType, ReactNode} from 'react';
 import {classNames, renderComponentOrNode} from '../../common/functions';
+import {Axis} from '../Axis';
 import {tag, tagIcon, tagVariants} from './index.css';
 
 /**
@@ -61,12 +62,12 @@ export const Tag = ({
 }) => {
   const icon = Icon ? <Icon className={tagIcon} /> : null;
   return (
-    <div
+    <Axis
       className={classNames(tag, tagVariants[variant], className)}
       title={alt}
     >
       {icon}
       {renderComponentOrNode(title)}
-    </div>
+    </Axis>
   );
 };

package/src/index.ts

@@ -1,4 +1,5 @@
 export {App} from './components/App/index.tsx';
+export {Axis} from './components/Axis/index.tsx';
 export {Button} from './components/Button/index.tsx';
 export {Card} from './components/Card/index.tsx';
 export {Checkbox} from './components/Checkbox/index.tsx';
@@ -8,6 +9,8 @@ export {Detail} from './components/Detail/index.tsx';
 export {Flyout} from './components/Flyout/index.tsx';
 export {Hr} from './components/Hr/index.tsx';
 export {Image} from './components/Image/index.tsx';
+export {ImageLabel} from './components/ImageLabel/index.tsx';
+export {Loading} from './components/Loading/index.tsx';
 export {Metric} from './components/Metric/index.tsx';
 export {Row} from './components/Row/index.tsx';
 export {Select} from './components/Select/index.tsx';