tinywidgets 1.3.12 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinywidgets",
-  "version": "1.3.12",
+  "version": "1.4.0",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinywidgets",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "./css": "./src/index.css.ts"
   },
   "dependencies": {
-    "@vanilla-extract/css": "^1.19.1",
+    "@vanilla-extract/css": "^1.20.0",
     "lucide-react": "^0.577.0",
     "react": "^19.2.4",
     "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/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,7 @@ 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 {Metric} from './components/Metric/index.tsx';
 export {Row} from './components/Row/index.tsx';
 export {Select} from './components/Select/index.tsx';