tinywidgets 0.0.10 → 1.0.0

package/.eslintrc.json

@@ -86,6 +86,7 @@
     "react/require-default-props": 0,
     "react/sort-comp": 0,
     "react/forbid-component-props": 0,
-    "react/button-has-type": 0
+    "react/button-has-type": 0,
+    "react/no-array-index-key": 0
   }
 }

package/package.json

@@ -1,33 +1,38 @@
 {
   "name": "tinywidgets",
-  "version": "0.0.10",
+  "description": "A collection of tiny, reusable, React components",
+  "version": "1.0.0",
+  "scripts": {
+    "prePublishPackage": "eslint . && tsc"
+  },
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinywidgets",
-  "module": "index.ts",
+  "module": "./src/index.ts",
   "devDependencies": {
-    "@types/react": "^18.3.5",
+    "@types/react": "^18.3.8",
     "@types/react-dom": "^18.3.0",
-    "@typescript-eslint/eslint-plugin": "^8.5.0",
-    "@typescript-eslint/parser": "^8.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.7.0",
+    "@typescript-eslint/parser": "^8.7.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-react": "^7.36.1",
     "eslint-plugin-react-hooks": "^4.6.2",
     "prettier": "^3.3.3",
     "typescript": "^5.6.2",
-    "@vanilla-extract/css": "^1.15.5",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "tinybase": "^5.3.0-beta.3"
+    "@vanilla-extract/css": "^1.15.5"
   },
   "exports": {
-    ".": "./index.ts",
-    "./utils": "./utils.ts",
-    "./css": "./index.css.ts"
+    ".": "./src/index.ts",
+    "./css": "./src/index.css.ts"
   },
-  "description": "reserved",
   "license": "MIT",
   "dependencies": {
-    "lucide-react": "^0.441.0"
+    "eslint-plugin-react-refresh": "^0.4.12",
+    "lucide-react": "^0.445.0",
+    "prism-react-renderer": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tinybase": "^5.3.1"
   }
 }

package/src/common/functions.tsx

@@ -0,0 +1,54 @@
+import React, {type ComponentType, type ReactNode} from 'react';
+import type {StyleRule} from '@vanilla-extract/css';
+import {screens} from '../css/screens';
+
+/**
+ * The `classNames` function returns a concatenated list of class names,
+ * filtering out any `null` or `undefined` values.
+ *
+ * This allows you to easily toggle classes based on conditions.
+ *
+ * @returns A string of space-separated class names.
+ * @example
+ * ```tsx
+ * const classes = classNames(
+ *   'class1',
+ *   false && 'class2',
+ *   true && 'class3',
+ * );
+ * // ...
+ * <Card className={classes}>
+ *   <code>{classes}</code>
+ * </Card>
+ * ```
+ * This example shows the function returning a class name list.
+ */
+export const classNames = (
+  ...classes: (string | boolean | null | undefined)[]
+) => classes.filter(Boolean).join(' ');
+
+export const renderComponentOrNode = (
+  ComponentOrNode: ComponentType | ReactNode,
+  fallback: ReactNode = null,
+) =>
+  ComponentOrNode instanceof Function ? (
+    <ComponentOrNode />
+  ) : (
+    (ComponentOrNode ?? fallback)
+  );
+
+export const large = (style: StyleRule) => ({
+  '@media': {[`screen and (min-width: ${screens.large}px)`]: style},
+});
+
+export const notLarge = (style: StyleRule) => ({
+  '@media': {[`screen and (max-width: ${screens.large}px)`]: style},
+});
+
+export const small = (style: StyleRule) => ({
+  '@media': {[`screen and (max-width: ${screens.small}px)`]: style},
+});
+
+export const notSmall = (style: StyleRule) => ({
+  '@media': {[`screen and (min-width: ${screens.small}px)`]: style},
+});

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

@@ -0,0 +1,81 @@
+import {dimensions, dimensionsClass} from '../../css/dimensions.css.ts';
+import {colors} from '../../css/colors.css.ts';
+import {large} from '../../common/functions.tsx';
+import {style} from '@vanilla-extract/css';
+
+export const app = style([dimensionsClass, {color: colors.foreground}]);
+
+export const appLayout = style({
+  display: 'flex',
+  height: '100dvh',
+  width: '100dvw',
+});
+
+export const header = style({
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  gap: dimensions.padding,
+  padding: dimensions.padding,
+  position: 'fixed',
+  boxShadow: colors.shadow,
+  backdropFilter: 'blur(8px)',
+  backgroundColor: colors.backgroundHaze,
+  left: 0,
+  right: 0,
+  height: dimensions.topNavHeight,
+  borderBottom: colors.border,
+  zIndex: 2,
+});
+
+export const topNav = style({
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  gap: dimensions.padding,
+
+  flex: 1,
+});
+
+export const sideNavButton = style(large({display: 'none'}));
+
+export const title = style({
+  display: 'flex',
+  alignItems: 'center',
+  gap: dimensions.padding,
+  ...large({
+    width: `calc(${dimensions.sideNavWidth} - 2 * ${dimensions.padding})`,
+  }),
+});
+
+export const sideNav = style({
+  position: 'fixed',
+  padding: dimensions.padding,
+  backgroundColor: colors.background2,
+  overflow: 'auto',
+  borderRight: colors.border,
+  width: dimensions.sideNavWidth,
+  bottom: 0,
+  left: `calc(-1.2 * ${dimensions.sideNavWidth})`,
+  top: dimensions.topNavHeight,
+  height: `calc(100dvh - ${dimensions.topNavHeight})`,
+  overscrollBehavior: 'contain',
+  transition: 'left .2s ease-in-out',
+  ...large({left: 0}),
+});
+
+export const sideNavOpen = style({left: 0});
+
+export const main = style({
+  flex: 1,
+  backgroundColor: colors.background,
+  overflow: 'auto',
+  padding: dimensions.padding,
+  paddingTop: `calc(${dimensions.topNavHeight} + ${dimensions.padding})`,
+});
+
+export const mainHasSideNav = style(
+  large({
+    paddingLeft: `calc(${dimensions.sideNavWidth} + ${dimensions.padding})`,
+  }),
+);

package/src/components/App/index.tsx

@@ -0,0 +1,177 @@
+import type {ComponentType, ReactNode} from 'react';
+import {
+  LocalStore,
+  useDark,
+  useDarkChoice,
+  useLocalStoreIsReady,
+  useToggleDarkChoiceCallback,
+} from '../../stores/LocalStore.tsx';
+import {Menu, Moon, Sun, SunMoon, X} from 'lucide-react';
+import {RouteStore, useRouteStoreIsReady} from '../../stores/RouteStore.tsx';
+import {
+  SessionStore,
+  useSessionStoreIsReady,
+  useSideNavIsOpen,
+  useToggleSideNavIsOpenCallback,
+} from '../../stores/SessionStore.tsx';
+import {
+  app,
+  appLayout,
+  header,
+  main,
+  mainHasSideNav,
+  sideNav,
+  sideNavButton,
+  sideNavOpen,
+  title,
+  topNav,
+} from './index.css.ts';
+import {classNames, renderComponentOrNode} from '../../common/functions.tsx';
+import {codeDark, codeLight} from '../../css/code.css.ts';
+import {colorsDark, colorsLight} from '../../css/colors.css.ts';
+import {Button} from '../Button/index.tsx';
+import {Provider} from 'tinybase/ui-react';
+import React from 'react';
+
+const darkIcons = [Sun, Moon, SunMoon];
+const darkChoices = ['Light always', 'Dark always', 'Auto'];
+
+/**
+ * The `App` component is the root component of a TinyWidgets application.
+ *
+ * It can be provided with optional components for different parts of the app
+ * layout, including the top left title, the side bar and the main content.
+ *
+ * If none of these props are present, the TinyWidgets layout won't be used, but
+ * you will still be able to enjoy its state management features, and any
+ * components within it will be correctly styled.
+ * @param props The props for the component.
+ * @returns The App component.
+ * @example
+ * ```tsx
+ * <App />
+ * ```
+ * This shows an empty App, but if you visit [the TinyWidgets
+ * website](https://tinywidgets.org) you'll see one in its full glory!
+ * @icon Lucide.PanelsTopLeft
+ */
+export const App = (props: {
+  /**
+   * An optional component, element, or string which renders the top left title
+   * of the application.
+   */
+  readonly title?: ComponentType | ReactNode;
+  /**
+   * An optional component, element, or string which renders navigation on the
+   * left side of the top navigation bar of the application.
+   */
+  readonly topNavLeft?: ComponentType | ReactNode;
+  /**
+   * An optional component, element, or string which renders navigation on the
+   * right side of the top navigation bar of the application.
+   */
+  readonly topNavRight?: ComponentType | ReactNode;
+  /**
+   * An optional component, element, or string which renders the left side bar
+   * of the application.
+   */
+  readonly sideNav?: ComponentType | ReactNode;
+  /**
+   * An optional component, element, or string which renders the main part of
+   * the application.
+   */
+  readonly main?: ComponentType | ReactNode;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+}) => {
+  return (
+    <Provider>
+      <Layout {...props} />
+      <SessionStore />
+      <LocalStore />
+      <RouteStore />
+    </Provider>
+  );
+};
+
+const Layout = ({
+  title: titleComponentOrNode,
+  topNavLeft: topNavLeftComponentOrNode,
+  topNavRight: topNavRightComponentOrNode,
+  sideNav: sideNavComponentOrNode,
+  main: mainComponentOrNode,
+  className,
+}: Parameters<typeof App>[0]) => {
+  const sessionStoreIsReady = useSessionStoreIsReady();
+  const routeStoreIsReady = useRouteStoreIsReady();
+  const localStoreIsReady = useLocalStoreIsReady();
+
+  const toggleDarkChoice = useToggleDarkChoiceCallback();
+
+  const toggleSideNavIsOpen = useToggleSideNavIsOpenCallback();
+  const sideNavIsOpen = useSideNavIsOpen();
+
+  const darkChoice = useDarkChoice();
+  const dark = useDark();
+
+  const hasLayout = [
+    titleComponentOrNode,
+    topNavLeftComponentOrNode,
+    topNavRightComponentOrNode,
+    sideNavComponentOrNode,
+    mainComponentOrNode,
+  ].some((componentOrNode) => componentOrNode);
+  const hasSideNav = sideNavComponentOrNode != null;
+
+  return sessionStoreIsReady && routeStoreIsReady && localStoreIsReady ? (
+    <div
+      className={classNames(
+        app,
+        hasLayout && appLayout,
+        dark ? colorsDark : colorsLight,
+        dark ? codeDark : codeLight,
+        className,
+      )}
+    >
+      {hasLayout ? (
+        <>
+          <header className={header}>
+            {hasSideNav ? (
+              <Button
+                variant="icon"
+                onClick={toggleSideNavIsOpen}
+                icon={sideNavIsOpen ? X : Menu}
+                className={sideNavButton}
+              />
+            ) : null}
+            <nav className={title}>
+              {renderComponentOrNode(titleComponentOrNode)}
+            </nav>
+            <nav className={topNav}>
+              {renderComponentOrNode(topNavLeftComponentOrNode, <div />)}
+              {renderComponentOrNode(topNavRightComponentOrNode, <div />)}
+            </nav>
+            <Button
+              variant="icon"
+              onClick={toggleDarkChoice}
+              icon={darkIcons[darkChoice]}
+              alt={darkChoices[darkChoice]}
+            />
+            {hasSideNav ? (
+              <nav
+                className={classNames(sideNav, sideNavIsOpen && sideNavOpen)}
+              >
+                {renderComponentOrNode(sideNavComponentOrNode)}
+              </nav>
+            ) : null}
+          </header>
+          <main className={classNames(main, hasSideNav && mainHasSideNav)}>
+            {renderComponentOrNode(mainComponentOrNode)}
+          </main>
+        </>
+      ) : null}
+    </div>
+  ) : null;
+};

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

@@ -0,0 +1,66 @@
+import {style, styleVariants} from '@vanilla-extract/css';
+import {colors} from '../../css/colors.css';
+import {dimensions} from '../../css/dimensions.css';
+
+export const button = style({
+  display: 'inline-flex',
+  justifyContent: 'space-between',
+  alignItems: 'center',
+  gap: dimensions.padding,
+  borderRadius: dimensions.radius,
+  textAlign: 'left',
+  cursor: 'pointer',
+  padding: '0.5rem 1rem',
+  outlineOffset: '-2px',
+  color: 'inherit',
+  overflow: 'hidden',
+  whiteSpace: 'nowrap',
+  transition: 'background-color 0.1s,border-color 0.1s',
+  flexShrink: 0,
+  border: 0,
+  alignSelf: 'center',
+  background: 'none',
+  selectors: {
+    '&:hover': {
+      backgroundColor: colors.backgroundHover,
+      color: colors.foregroundBright,
+    },
+  },
+});
+
+export const buttonVariants = styleVariants({
+  default: {
+    boxShadow: colors.shadow,
+    border: colors.border,
+    backgroundColor: colors.background,
+  },
+  accent: {
+    boxShadow: colors.shadow,
+    backgroundColor: colors.accent,
+    color: colors.accentContrast,
+    selectors: {
+      '&:hover': {
+        backgroundColor: colors.accentHover,
+      },
+    },
+  },
+  ghost: {},
+  item: {width: '100%'},
+  icon: {padding: '0.25rem'},
+});
+
+export const currentStyle = style({
+  backgroundColor: colors.backgroundHover,
+  color: colors.foregroundBright,
+});
+
+export const titleStyle = style({
+  flex: '1 1 auto',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+});
+
+export const titleStyleRight = style({
+  flex: '0 0 auto',
+  overflow: 'hidden',
+});

package/src/components/Button/index.tsx

@@ -0,0 +1,206 @@
+import type {ComponentType, ReactNode, Ref} from 'react';
+import React, {forwardRef, useCallback} from 'react';
+import {
+  button,
+  buttonVariants,
+  currentStyle,
+  titleStyle,
+  titleStyleRight,
+} from './index.css.ts';
+import {classNames, renderComponentOrNode} from '../../common/functions.tsx';
+import {iconSize} from '../../css/dimensions.css.ts';
+
+/**
+ * The `Button` component displays an button, with a number of common variants.
+ *
+ * @param props The props for the component.
+ * @returns The Button component.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="TinyWidgets"
+ *   onClick={() => alert('Clicked!')}
+ * />
+ * ```
+ * This example shows the `default` variant of the Button component.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="TinyWidgets"
+ *   icon={Lucide.Grid3x3}
+ * />
+ * ```
+ * This example shows the `default` variant of the Button component with a left
+ * icon.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="TinyWidgets"
+ *   iconRight={Lucide.LogIn}
+ * />
+ * ```
+ * This example shows the `default` variant of the Button component with a right
+ * icon.
+ * @example
+ * ```tsx
+ * <Button
+ *   icon={Lucide.Sun}
+ *   variant="icon"
+ * />
+ * ```
+ * This example shows the `icon` variant of the Button component. It is best
+ * used without a title.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="TinyWidgets"
+ *   variant="accent"
+ * />
+ * ```
+ * This example shows the `accent` variant of the Button component.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="tinybase.org"
+ *   iconRight={Lucide.SquareArrowOutUpRight}
+ *   variant="accent"
+ *   href="https://tinybase.org"
+ * />
+ * ```
+ * This example shows the `accent` variant of the Button component with an icon,
+ * and that launches a new link.
+ * @example
+ * ```tsx
+ * <Button
+ *   title="TinyWidgets"
+ *   variant="ghost"
+ * />
+ * ```
+ * This example shows the `ghost` variant of the Button component.
+ * @example
+ * ```tsx
+ * <Button
+ *   variant="item"
+ *   icon={Lucide.Grid3x3}
+ *   title="TinyWidgets"
+ *   titleRight={<i>4</i>}
+ *   iconRight={Lucide.CircleHelp}
+ * />
+ * ```
+ * This example shows the `item` variant of the Button component with both left
+ * and right titles and icons. This is suitable for use as a link in a
+ * navigational list, such as a side bar.
+ * @example
+ * ```tsx
+ * <Button
+ *   variant="item"
+ *   icon={Lucide.Grid3x3}
+ *   title="TinyWidgets"
+ *   current={true}
+ * />
+ * ```
+ * This example shows the `item` variant of the Button component, marked as
+ * 'current'.
+ * @icon Lucide.RectangleHorizontal
+ */
+export const Button = forwardRef(
+  (
+    {
+      icon: Icon,
+      title: titleComponentOrNode,
+      titleRight: titleRightComponentOrNode,
+      iconRight: IconRight,
+      onClick,
+      variant = 'default',
+      current,
+      href,
+      alt,
+      className,
+    }: {
+      /**
+       * An optional component which renders an icon for the button, and which
+       * must accept a className prop.
+       */
+      readonly icon?: ComponentType<{className?: string}>;
+      /**
+       * An optional component, element, or string which renders the title of
+       * the button.
+       */
+      readonly title?: ComponentType | ReactNode;
+      /**
+       * An optional component, element, or string which renders a second title
+       * on the right side of the button.
+       */
+      readonly titleRight?: ComponentType | ReactNode;
+      /**
+       * An optional component which renders a second icon for the button, and
+       * which must accept a className prop.
+       */
+      readonly iconRight?: ComponentType<{className?: string}>;
+      /**
+       * A handler called when the user clicks on the button.
+       */
+      readonly onClick?: () => void;
+      /**
+       * A variant of the button, one of:
+       * - `default`
+       * - `icon`
+       * - `accent`
+       * - `ghost`
+       * - `item`
+       */
+      readonly variant?: keyof typeof buttonVariants;
+      /**
+       * A flag that indicates that an `item` button is 'current' and therefore
+       * highlighted.
+       */
+      readonly current?: boolean;
+      /**
+       * A URL that can be used instead of an `onClick` to launch a new web
+       * page, much like a link.
+       */
+      readonly href?: string;
+      /**
+       * Alternative text shown when the user hovers over the button.
+       */
+      readonly alt?: string;
+      /**
+       * An extra CSS class name for the component.
+       */
+      readonly className?: string;
+    },
+    ref: Ref<HTMLButtonElement>,
+  ) => {
+    const hrefClick = useCallback(
+      () => (href ? open(href, '_blank', 'noreferrer') : null),
+      [href],
+    );
+
+    return (
+      <button
+        className={classNames(
+          button,
+          buttonVariants[variant],
+          current && currentStyle,
+          className,
+        )}
+        onClick={onClick ?? hrefClick}
+        title={alt}
+        ref={ref}
+      >
+        {Icon ? <Icon className={iconSize} /> : null}
+        {titleComponentOrNode ? (
+          <span className={titleStyle}>
+            {renderComponentOrNode(titleComponentOrNode)}
+          </span>
+        ) : null}
+        {titleRightComponentOrNode ? (
+          <span className={titleStyleRight}>
+            {renderComponentOrNode(titleRightComponentOrNode)}
+          </span>
+        ) : null}
+        {IconRight ? <IconRight className={iconSize} /> : null}
+      </button>
+    );
+  },
+);

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

@@ -0,0 +1,12 @@
+import {colors} from '../../css/colors.css';
+import {dimensions} from '../../css/dimensions.css';
+import {style} from '@vanilla-extract/css';
+
+export const card = style({
+  padding: dimensions.padding,
+  borderRadius: dimensions.radius,
+  boxShadow: colors.shadow,
+  border: colors.border,
+  height: 'fit-content',
+  overflow: 'auto',
+});

package/src/components/Card/index.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import type {ReactNode} from 'react';
+import {card} from './index.css';
+import {classNames} from '../../common/functions';
+
+/**
+ * The `Card` component displays a simple rectangular container.
+ *
+ * @param props The props for the component.
+ * @returns Card Row component.
+ * @example
+ * ```tsx
+ * <Card>
+ *   <h1>Welcome</h1>
+ *   <Hr />
+ *   <p>We hope you enjoy TinyWidgets</p>
+ * </Card>
+ * ```
+ * This example shows a simple card.
+ * @icon Lucide.Square
+ */
+export const Card = ({
+  className,
+  children,
+}: {
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+  /**
+   * The children of the component, that go inside the card.
+   */
+  readonly children: ReactNode;
+}) => <div className={classNames(card, className)}>{children}</div>;