tinywidgets 0.0.11 → 1.0.0

package/src/components/Row/index.tsx

@@ -0,0 +1,104 @@
+import {row, rowVariants} from './index.css';
+import React from 'react';
+import type {ReactNode} from 'react';
+import {classNames} from '../../common/functions';
+
+/**
+ * The `Row` component displays a row of 'cell' components, with a number of
+ * common variants representing the relative sizes of those cells within it.
+ *
+ * @param props The props for the component.
+ * @returns The Row component.
+ * @example
+ * ```tsx
+ * <Row>
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>1</div>
+ * </Row>
+ * ```
+ * This example shows the default `1|1` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="1|2">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>2</div>
+ * </Row>
+ * ```
+ * This example shows the `1|2` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="2|1">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>2</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>1</div>
+ * </Row>
+ * ```
+ * This example shows the `2|1` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="1|1|1">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 120)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 240)'}}>1</div>
+ * </Row>
+ * ```
+ * This example shows the `1|1|1` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="1|3">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>3</div>
+ * </Row>
+ * ```
+ * This example shows the `1|3` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="3|1">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>3</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>1</div>
+ * </Row>
+ * ```
+ * This example shows the `3|1` variant of the Row component.
+ * @example
+ * ```tsx
+ * <Row variant="1|1|1|1">
+ *   <div style={{background: 'oklch(50% 0.11 0)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 90)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 180)'}}>1</div>
+ *   <div style={{background: 'oklch(50% 0.11 270)'}}>1</div>
+ * </Row>
+ * ```
+ * This example shows the `1|1|1|1` variant of the Row component.
+ * @icon Lucide.Columns3
+ */
+export const Row = ({
+  variant = '1|1',
+  className,
+  children,
+}: {
+  /**
+   * A variant of the row, representing the relative 'cell' sizes within it, one
+   * of:
+   * - `1|1`
+   * - `1|2`
+   * - `2|1`
+   * - `1|1|1`
+   * - `1|3`
+   * - `3|1`
+   * - `1|1|1|1`
+   */
+  readonly variant?: keyof typeof rowVariants;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+  /**
+   * The children of the component, each occupying one 'cell'.
+   */
+  readonly children: ReactNode;
+}) => {
+  return (
+    <div className={classNames(row, rowVariants[variant], className)}>
+      {children}
+    </div>
+  );
+};

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

@@ -0,0 +1,16 @@
+import {dimensions} from '../../css/dimensions.css.ts';
+import {notLarge} from '../../common/functions.tsx';
+import {style} from '@vanilla-extract/css';
+
+export const summary = style({
+  display: 'grid',
+  width: '100%',
+  gap: dimensions.padding,
+  gridTemplateColumns: `6rem 1fr`,
+  ...notLarge({gridTemplateColumns: '1fr'}),
+});
+
+export const image = style({
+  height: '6rem',
+  width: '6rem',
+});

package/src/components/Summary/index.tsx

@@ -0,0 +1,59 @@
+import type {ComponentType, ReactNode} from 'react';
+import {image, summary} from './index.css';
+import {Image} from '../Image';
+import React from 'react';
+import {classNames} from '../../common/functions';
+
+/**
+ * The `Summary` component displays an image on the left, and other content
+ * (probably text) on the right.
+ *
+ * @param props The props for the component.
+ * @returns The Summary component.
+ * @example
+ * ```tsx
+ * <Summary src="/favicon.svg">
+ *   <h2>TinyWidgets</h2>
+ *   <p>Widgets for the modern web.</p>
+ * </Summary>
+ * ```
+ * This example shows a default Summary component.
+ * @icon Lucide.LayoutList
+ */
+export const Summary = ({
+  src,
+  icon: Icon,
+  className,
+  children,
+}: {
+  /**
+   * An optional component which renders an icon for the summary, and which
+   * must accept a className prop.
+   */
+  readonly icon?: ComponentType<{className?: string}>;
+  /**
+   * The source of the image, which used if the `icon` prop is not present.
+   */
+  readonly src?: string;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+  /**
+   * The children of the component, shown to the right of the image.
+   */
+  readonly children: ReactNode;
+}) => {
+  return (
+    <div className={classNames(summary, className)}>
+      {Icon ? (
+        <Icon className={image} />
+      ) : src ? (
+        <Image src={src} className={image} />
+      ) : (
+        <div />
+      )}
+      <div>{children}</div>
+    </div>
+  );
+};

package/src/{Tag → components/Tag}/index.css.ts

@@ -1,7 +1,9 @@
 import {style, styleVariants} from '@vanilla-extract/css';
-import {theme} from '../index.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',
@@ -10,14 +12,15 @@ export const tag = style({
   flexShrink: 0,
 });
 
-export const tagVariant = styleVariants({
+export const tagVariants = styleVariants({
   default: {
-    backgroundColor: theme.backgroundHover,
-    color: theme.foreground2,
+    backgroundColor: colors.backgroundHover,
+    color: colors.foregroundDim,
   },
   accent: {
-    backgroundColor: theme.accent,
-    color: theme.accentContrast,
+    backgroundColor: colors.accent,
+    color: colors.accentContrast,
+    boxShadow: colors.shadow,
   },
 });
 

package/src/components/Tag/index.tsx

@@ -0,0 +1,73 @@
+import type {ComponentType, ReactNode} from 'react';
+import {classNames, renderComponentOrNode} from '../../common/functions';
+import {tag, tagIcon, tagVariants} from './index.css';
+import React from 'react';
+
+/**
+ * The `Tag` component displays a small rectangular tag, suitable for minimal
+ * amounts of metadata, such as a notification count.
+ *
+ * @param props The props for the component.
+ * @returns The Tag component.
+ * @example
+ * ```tsx
+ * <Tag
+ *   title="TinyWidgets"
+ * />
+ * ```
+ * This example shows the `default` variant of the Tag component.
+ * @example
+ * ```tsx
+ * <Tag
+ *   title="57"
+ *   variant="accent"
+ *   icon={Lucide.Bell}
+ *   alt="You have lots of notifications"
+ * />
+ * ```
+ * This example shows the `accent` variant of the Tag component with an icon.
+ * @icon Lucide.RectangleEllipsis
+ */
+export const Tag = ({
+  icon: Icon,
+  title,
+  variant = 'default',
+  alt,
+  className,
+}: {
+  /**
+   * An optional component which renders an icon for the tag, and which
+   * must accept a className prop.
+   */
+  readonly icon?: ComponentType<{className?: string}>;
+  /**
+   * An optional component, element, or string which renders the title of
+   * the tag.
+   */
+  readonly title?: ComponentType | ReactNode;
+  /**
+   * A variant of the tag, one of:
+   * - `default`
+   * - `accent`
+   */
+  readonly variant?: keyof typeof tagVariants;
+  /**
+   * Alternative text shown when the user hovers over the component.
+   */
+  readonly alt?: string;
+  /**
+   * An extra CSS class name for the component.
+   */
+  readonly className?: string;
+}) => {
+  const icon = Icon ? <Icon className={tagIcon} /> : null;
+  return (
+    <div
+      className={classNames(tag, tagVariants[variant], className)}
+      title={alt}
+    >
+      {icon}
+      {renderComponentOrNode(title)}
+    </div>
+  );
+};

package/src/css/code.css.ts

@@ -0,0 +1,112 @@
+/* eslint-disable max-len */
+import {createTheme, createThemeContract} from '@vanilla-extract/css';
+
+/**
+ * The `code` object exposes the CSS variables used by TinyWidgets for coloring
+ * the code blocks, so that you can use them directly in your own application.
+ *
+ * The values are derived from the [prism-one-dark](https://github.com/PrismJS/prism-themes/blob/master/themes/prism-one-dark.css) and [prism-one-light](https://github.com/PrismJS/prism-themes/blob/master/themes/prism-one-light.css) themes. The full set of members is:
+ * - `mono-1`
+ * - `mono-2`
+ * - `mono-3`
+ * - `hue-1`
+ * - `hue-2`
+ * - `hue-3`
+ * - `hue-4`
+ * - `hue-5`
+ * - `hue-5-2`
+ * - `hue-6`
+ * - `hue-6-2`
+ * - `syntax-fg`
+ * - `syntax-bg`
+ * - `syntax-gutter`
+ * - `syntax-guide`
+ * - `syntax-accent`
+ *
+ * You can use these variables directly in React components that take style
+ * attributes, like this:
+ *
+ * ```tsx
+ * <code style={{color: code['hue-2']}}>function</code>
+ * ```
+ *
+ * And if you are using Vanilla-Extract for your app's styles, use them in your
+ * style declarations like this:
+ *
+ * ```tsx
+ * export const functionStyle = style({color: code['hue-2']});
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <Code code={code['mono-1']} />
+ *   <Hr />
+ *   <Row variant="1|1|1">
+ *     <code style={{color: code['hue-2']}}>function</code>
+ *     <code style={{color: code['hue-3']}}>keyword</code>
+ *     <code style={{color: code['hue-4']}}>string</code>
+ *   </Row>
+ * </Card>
+ * ```
+ * This example shows one of the values within the `code` object, and then
+ * applies some of them to custom code components. Change the dark mode to see
+ * the colors respond.
+ * @icon Lucide.Palette
+ */
+export const code = createThemeContract({
+  'mono-1': null,
+  'mono-2': null,
+  'mono-3': null,
+  'hue-1': null,
+  'hue-2': null,
+  'hue-3': null,
+  'hue-4': null,
+  'hue-5': null,
+  'hue-5-2': null,
+  'hue-6': null,
+  'hue-6-2': null,
+  'syntax-fg': null,
+  'syntax-bg': null,
+  'syntax-gutter': null,
+  'syntax-guide': null,
+  'syntax-accent': null,
+});
+
+export const codeLight = createTheme(code, {
+  'mono-1': `hsl(230, 8%, 24%)`,
+  'mono-2': `hsl(230, 6%, 44%)`,
+  'mono-3': `hsl(230, 4%, 64%)`,
+  'hue-1': `hsl(198, 99%, 37%)`,
+  'hue-2': `hsl(221, 87%, 60%)`,
+  'hue-3': `hsl(301, 63%, 40%)`,
+  'hue-4': `hsl(119, 34%, 47%)`,
+  'hue-5': `hsl(5, 74%, 59%)`,
+  'hue-5-2': `hsl(344, 84%, 43%)`,
+  'hue-6': `hsl(35, 99%, 36%)`,
+  'hue-6-2': `hsl(35, 99%, 40%)`,
+  'syntax-fg': `hsl(230, 8%, 24%)`,
+  'syntax-bg': `hsl(230, 1%, 98%)`,
+  'syntax-gutter': `hsl(230, 1%, 62%)`,
+  'syntax-guide': `hsla(230, 8%, 24%, 0.2)`,
+  'syntax-accent': `hsl(230, 100%, 66%)`,
+});
+
+export const codeDark = createTheme(code, {
+  'mono-1': `hsl(220, 14%, 71%)`,
+  'mono-2': `hsl(220, 9%, 55%)`,
+  'mono-3': `hsl(220, 10%, 40%)`,
+  'hue-1': `hsl(187, 47%, 55%)`,
+  'hue-2': `hsl(207, 82%, 66%)`,
+  'hue-3': `hsl(286, 60%, 67%)`,
+  'hue-4': `hsl(95, 38%, 62%)`,
+  'hue-5': `hsl(355, 65%, 65%)`,
+  'hue-5-2': `hsl(5, 48%, 51%)`,
+  'hue-6': `hsl(29, 54%, 61%)`,
+  'hue-6-2': `hsl(39, 67%, 69%)`,
+  'syntax-fg': `hsl(220, 14%, 71%)`,
+  'syntax-bg': `hsl(220, 13%, 18%)`,
+  'syntax-gutter': `hsl(220, 14%, 45%)`,
+  'syntax-guide': `hsla(220, 14%, 71%, 0.15)`,
+  'syntax-accent': `hsl(220, 100%, 66%)`,
+});

package/src/css/colors.css.ts

@@ -0,0 +1,124 @@
+import {
+  createTheme,
+  createThemeContract,
+  fallbackVar,
+  globalStyle,
+} from '@vanilla-extract/css';
+
+/**
+ * The `colors` object exposes the CSS variables used by TinyWidgets for color
+ * theming, so that you can use them directly in your own application.
+ *
+ * The full set of members is:
+ * - `accentHue`
+ * - `backgroundHue`
+ * - `accent`
+ * - `accentLight`
+ * - `accentHover`
+ * - `accentContrast`
+ * - `background`
+ * - `background2`
+ * - `backgroundHaze`
+ * - `backgroundHover`
+ * - `foreground`
+ * - `foregroundBright`
+ * - `foregroundDim`
+ * - `border`
+ * - `shadow`
+ *
+ * You can use these variables directly in React components that take style
+ * attributes, like this:
+ *
+ * ```tsx
+ * <div style={{color: colors.accent}}>Accent</div>
+ * ```
+ *
+ * And if you are using Vanilla-Extract for your app's styles, use them in your
+ * style declarations like this:
+ *
+ * ```tsx
+ * export const titleStyle = style({color: colors.accent});
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <Code code={colors.accentHue} />
+ *   <Hr />
+ *   <div style={{
+ *     color: colors.accent,
+ *     background: colors.background2,
+ *     border: colors.border,
+ *     boxShadow: colors.shadow,
+ *     textAlign: 'center',
+ *   }}>
+ *     Accent on a background
+ *   </div>
+ * </Card>
+ * ```
+ * This example shows one of the values within the `colors` object, and then
+ * applies some of them to a custom component. Change the dark mode to see the
+ * background respond.
+ * @icon Lucide.Palette
+ */
+export const colors = createThemeContract({
+  accentHue: null,
+  backgroundHue: null,
+  accent: null,
+  accentLight: null,
+  accentHover: null,
+  accentContrast: null,
+  background: null,
+  background2: null,
+  backgroundHaze: null,
+  backgroundHover: null,
+  foreground: null,
+  foregroundBright: null,
+  foregroundDim: null,
+  border: null,
+  shadow: null,
+});
+
+const common = {
+  accentHue: fallbackVar('var(--tinyWidgets-accentHue)', '8'),
+  backgroundHue: fallbackVar(
+    'var(--tinyWidgets-backgroundHue)',
+    `calc(${colors.accentHue} + 180)`,
+  ),
+  accent: `oklch(50% .11 ${colors.accentHue})`,
+  accentLight: `oklch(71% .16 ${colors.accentHue})`,
+  accentHover: `oklch(45% .1 ${colors.accentHue})`,
+  accentContrast: '#fff',
+};
+
+export const colorsLight = createTheme(colors, {
+  ...common,
+  background: `oklch(99% .01 ${colors.backgroundHue})`,
+  background2: `oklch(95% .01 ${colors.backgroundHue})`,
+  backgroundHaze: `oklch(99% .01 ${colors.backgroundHue} / .5)`,
+  backgroundHover: `oklch(90% .01 ${colors.backgroundHue})`,
+  foreground: `oklch(50% .01 ${colors.accentHue})`,
+  foregroundBright: `oklch(10% .01 ${colors.accentHue})`,
+  foregroundDim: `oklch(60% .01 ${colors.accentHue})`,
+  border: `1px solid oklch(90% .01 ${colors.backgroundHue})`,
+  shadow: '0 1px 4px 0 hsl(0 0 20 / .1)',
+});
+globalStyle(`html:has(${colorsLight})`, {
+  backgroundColor: '#fff',
+});
+
+export const colorsDark = createTheme(colors, {
+  ...common,
+  background: `oklch(20% .01 ${colors.backgroundHue})`,
+  background2: `oklch(15% .01 ${colors.backgroundHue})`,
+  backgroundHaze: `oklch(21% 0% ${colors.backgroundHue} / .5)`,
+  backgroundHover: `oklch(25% .01 ${colors.backgroundHue})`,
+  foreground: `oklch(85% .01 ${colors.accentHue})`,
+  foregroundBright: `oklch(95% .01 ${colors.accentHue})`,
+  foregroundDim: `oklch(60% .01 ${colors.accentHue})`,
+  border: `1px solid oklch(30% .01 ${colors.backgroundHue})`,
+  shadow: '0 1px 4px 0 #000',
+});
+globalStyle(`html:has(${colorsDark})`, {
+  backgroundColor: '#000',
+});

package/src/css/dimensions.css.ts

@@ -0,0 +1,67 @@
+import {createTheme, fallbackVar, style} from '@vanilla-extract/css';
+
+const classAndObject = createTheme({
+  logo: fallbackVar('var(--tinyWidgets-logo)', '2rem'),
+  avatar: fallbackVar('var(--tinyWidgets-avatar)', '2rem'),
+  icon: fallbackVar('var(--tinyWidgets-icon)', '1rem'),
+  padding: fallbackVar('var(--tinyWidgets-padding)', '1rem'),
+  radius: fallbackVar('var(--tinyWidgets-radius)', '0.5rem'),
+  sideNavWidth: fallbackVar('var(--tinyWidgets-sideNavWidth)', '20rem'),
+  topNavHeight: fallbackVar('var(--tinyWidgets-topNavHeight)', '4rem'),
+});
+export const dimensionsClass = classAndObject[0];
+
+/**
+ * The `dimensions` object exposes the CSS variables used by TinyWidgets for
+ * various sizes and lengths, so that you can use them directly in your own
+ * application.
+ *
+ * The full set of members is:
+ * - `logo`
+ * - `avatar`
+ * - `icon`
+ * - `padding`
+ * - `radius`
+ * - `sideNavWidth`
+ * - `topNavHeight`
+ *
+ * You can use these variables directly in React components that take style
+ * attributes, like this:
+ *
+ * ```tsx
+ * <div style={{width: dimensions.logo, height: dimensions.logo}} />
+ * ```
+ *
+ * And if you are using Vanilla-Extract for your app's styles, use them in your
+ * style declarations like this:
+ *
+ * ```tsx
+ * export const logoStyle = style({
+ *   width: dimensions.logo,
+ *   height: dimensions.logo,
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   <Code code={dimensions['logo']} />
+ *   <Hr />
+ *   <div style={{
+ *     width: dimensions.logo,
+ *     height: dimensions.logo,
+ *     background: 'oklch(50% 0.11 0)',
+ *   }}/>
+ * </Card>
+ * ```
+ * This example shows one of the values within the `dimensions` object, and then
+ * applies some of them to a custom component.
+ * @icon Lucide.Ruler
+ */
+export const dimensions = classAndObject[1];
+
+export const iconSize = style({
+  flexShrink: 0,
+  height: dimensions.icon,
+  width: dimensions.icon,
+});

package/src/css/global.css.ts

@@ -0,0 +1,11 @@
+import {globalStyle} from '@vanilla-extract/css';
+import {small} from '../common/functions';
+
+globalStyle('*', {
+  margin: 0,
+  padding: 0,
+  boxSizing: 'border-box',
+  color: 'inherit',
+  fontSize: 'inherit',
+  ...small({fontSize: '0.85rem'}),
+});

package/src/css/screens.ts

@@ -0,0 +1,15 @@
+/**
+ * The `screens` object contains the media query breakpoints that TinyWidget
+ * uses to distinguish small, medium, and large screens.
+ *
+ * Currently, the main impact of the `large` member is that screens narrower
+ * than this number of pixels will get a collapsed side bar. Screens narrower
+ * than the `small` number of pixels will get a slightly smaller font.
+ * @example
+ * ```tsx
+ * <Code code={JSON.stringify(screens, null, 2)} />
+ * ```
+ * This example gets the breakpoint values.
+ * @icon Lucide.Ruler
+ */
+export const screens = {small: 448, large: 768};